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

package/dist/types/lib/operators/process-operators.d.ts

@@ -1,11 +1,55 @@
 import type { Observable } from 'rxjs';
 import { IProcessOperators, ProcessOperator } from './types';
+/**
+ * ProcessOperators class manages a collection of process operators
+ * and provides methods to add, set, get, and process these operators.
+ * It implements the IProcessOperators interface for type T.
+ *
+ * @template T The type of data that the process operators work with
+ */
 export declare class ProcessOperators<T> implements IProcessOperators<T> {
+    /**
+     * A record of process operators keyed by a string.
+     * This property is used to store and manage the collection of process operators
+     * that are used by the `ProcessOperators` class.
+     */
     protected _operators: Record<string, ProcessOperator<T>>;
+    /**
+     * Accessor for the collection of process operators.
+     * @returns The record of process operators.
+     */
     get operators(): Record<string, ProcessOperator<T>>;
+    /**
+     * Constructs a new instance of the ProcessOperators class.
+     * @param operators - An optional object containing process operators.
+     *                    It can be either an instance of IProcessOperators<T> or a record of string keys and ProcessOperator<T> values.
+     */
     constructor(operators?: IProcessOperators<T> | Record<string, ProcessOperator<T>>);
+    /**
+     * Adds a new operator to the collection.
+     * @param key The key under which the operator is stored.
+     * @param operator The operator to be added.
+     * @returns The instance of ProcessOperators for chaining.
+     * @throws Error if an operator with the same key already exists.
+     */
     add(key: string, operator: ProcessOperator<T>): ProcessOperators<T>;
+    /**
+     * Sets or updates an operator in the collection.
+     * @param key The key under which the operator is stored.
+     * @param operator The operator to be set.
+     * @returns The instance of ProcessOperators for chaining.
+     */
     set(key: string, operator: ProcessOperator<T>): ProcessOperators<T>;
+    /**
+     * Retrieves an operator from the collection by its key.
+     * @param key The key of the operator to retrieve.
+     * @returns The retrieved operator.
+     */
     get(key: string): ProcessOperator<T>;
+    /**
+     * Processes an input request through the chain of operators.
+     * @param request The request to be processed.
+     * @returns An Observable of the processed request.
+     */
     process(request: T): Observable<T>;
 }

package/dist/types/lib/operators/request-operator-header.d.ts

@@ -1,4 +1,11 @@
 import type { FetchRequest } from '../client';
 import type { ProcessOperator } from './types';
+/**
+ * Creates a process operator that adds a header to the request.
+ *
+ * @param key - The header key to add.
+ * @param value - The header value to add.
+ * @returns A process operator that adds the specified header to the request.
+ */
 export declare const requestOperatorHeader: <T extends FetchRequest = FetchRequest>(key: string, value: string) => ProcessOperator<T>;
 export default requestOperatorHeader;

package/dist/types/lib/operators/types.d.ts

@@ -1,15 +1,72 @@
 import type { Observable } from 'rxjs';
 import type { FetchRequest } from '../client';
+/**
+ * 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.
+ */
 export interface IProcessOperators<T> {
+    /**
+     * Gets the operators registered in the collection.
+     */
     get operators(): Record<string, ProcessOperator<T>>;
+    /**
+     * Adds a new operator to the collection.
+     * @param key The key to identify the operator.
+     * @param operator The process operator to add.
+     * @returns The updated collection of process operators.
+     * @throws An error if the operator is already defined.
+     */
     add(key: string, operator: ProcessOperator<T>): IProcessOperators<T>;
+    /**
+     * Adds or sets a process operator in the collection.
+     * @param key The key to identify the operator.
+     * @param operator The process operator to add or set.
+     * @returns The updated collection of process operators.
+     */
     set(key: string, operator: ProcessOperator<T>): IProcessOperators<T>;
+    /**
+     * Gets a process operator from the collection.
+     * @param key The key of the operator to retrieve.
+     * @returns The process operator associated with the key, or undefined if the key is invalid.
+     */
     get(key: string): ProcessOperator<T>;
+    /**
+     * Processes the registered process operators.
+     * @param request The request to process.
+     * @returns An observable that emits the processed request.
+     */
     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> {
+    /**
+     * Set header that will apply on all requests done by consumer @see {HttpClient}
+     * @param key - name of header
+     * @param value  - header value
+     */
     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/dist/types/lib/selectors/blob-selector.d.ts

@@ -1,2 +1,10 @@
-export declare const blobSelector: <TResponse extends Response = Response>(response: TResponse) => Promise<Blob>;
+import type { ResponseSelector } 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 declare const blobSelector: ResponseSelector;
 export default blobSelector;

package/dist/types/lib/selectors/index.d.ts

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

package/dist/types/lib/selectors/json-selector.d.ts

@@ -1,2 +1,17 @@
-export declare const jsonSelector: <TType = unknown, TResponse extends Response = Response>(response: TResponse) => Promise<TType>;
+import type { ResponseSelector } from '../client/types';
+/**
+ * Asynchronously parses the JSON data from a given HTTP 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 declare const jsonSelector: ResponseSelector;
 export default jsonSelector;

package/dist/types/module.d.ts

@@ -3,13 +3,48 @@ import { IHttpClientConfigurator, HttpClientOptions } from './configurator';
 import { IHttpClientProvider } from './provider';
 import type { Module, ModuleConfigType, IModuleConfigurator } from '@equinor/fusion-framework-module';
 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>, IHttpClientConfigurator<HttpClientMsal>, [
     MsalModule
 ]>;
+/**
+ * HTTP module with MSAL authentication.
+ */
 export declare const module: HttpMsalModule;
+/**
+ * Configures the HTTP module with MSAL authentication.
+ */
 export declare const configureHttp: <TRef = unknown>(configure: (config: ModuleConfigType<HttpMsalModule>, ref?: TRef) => void) => IModuleConfigurator<HttpMsalModule, TRef>;
+/**
+ * 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 declare const configureHttpClient: <TRef = unknown>(name: string, args: HttpClientOptions<HttpClientMsal>) => IModuleConfigurator<HttpMsalModule, TRef>;
+/**
+ * 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/dist/types/provider.d.ts

@@ -6,18 +6,95 @@ export declare class ClientNotFoundException extends Error {
     constructor(message: string);
 }
 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>>;
+    /**
+     * 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;
+    /**
+     * 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
+     * ```ts
+     * config.http.configureClient('foobar', (client) => {
+     *   client.ctor = MyClient;
+     *   client.uri = 'https://foobar.com';
+     * });
+     */
     createCustomClient<T extends HttpClient>(key: string): T;
 }
+/**
+ * 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 declare class HttpClientProvider<TClient extends IHttpClient = IHttpClient> implements IHttpClientProvider<TClient> {
     protected config: IHttpClientConfigurator<TClient>;
+    /**
+     * Gets the default HTTP request handler for the HTTP client provider.
+     * @returns The default HTTP request handler.
+     */
     get defaultHttpRequestHandler(): IHttpRequestHandler<HttpClientRequestInitType<TClient>>;
     constructor(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.
+     */
     hasClient(key: string): boolean;
+    /**
+     * 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.
+     */
     createClient(keyOrConfig: string | HttpClientOptions<TClient>): 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.
+     */
     createCustomClient<T extends HttpClient>(key: string): 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/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "5.2.3";
+export declare const version = "6.0.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-http",
-  "version": "5.2.3",
+  "version": "6.0.1",
   "description": "",
   "main": "dist/esm/index.js",
   "types": "index.d.ts",
@@ -55,12 +55,12 @@
   },
   "dependencies": {
     "rxjs": "^7.8.1",
-    "@equinor/fusion-framework-module": "^4.3.1",
-    "@equinor/fusion-framework-module-msal": "^3.1.1"
+    "@equinor/fusion-framework-module": "^4.3.2",
+    "@equinor/fusion-framework-module-msal": "^3.1.2"
   },
   "devDependencies": {
-    "typescript": "^5.4.2",
-    "vitest": "^1.6.0"
+    "typescript": "^5.5.3",
+    "vitest": "^2.0.1"
   },
   "scripts": {
     "build": "tsc -b",

package/src/configurator.ts

@@ -3,10 +3,24 @@ import { HttpRequestHandler } from './lib/operators';
 import type { FetchRequest, IHttpClient } from './lib/client';
 import type { IHttpRequestHandler, IHttpResponseHandler } from './lib/operators';
 
+/**
+ * Represents the options for constructing an `IHttpClient` instance.
+ *
+ * @template TInit - The type of the initial request object used by the `IHttpClient` instance.
+ * @property {IHttpRequestHandler<TInit>} requestHandler - The request handler to be used by the `IHttpClient` instance.
+ */
 interface HttpClientConstructorOptions<TInit extends FetchRequest> {
     requestHandler: IHttpRequestHandler<TInit>;
 }
 
+/**
+ * Represents a constructor for an `IHttpClient` instance.
+ *
+ * @template TClient - The type of the `IHttpClient` instance to be constructed.
+ * @param uri - The base URI for the `IHttpClient` instance.
+ * @param options - The options for constructing the `IHttpClient` instance, including the request handler.
+ * @returns A new instance of the `TClient` type.
+ */
 interface HttpClientConstructor<TClient extends IHttpClient> {
     new (
         uri: string,
@@ -14,15 +28,38 @@ interface HttpClientConstructor<TClient extends IHttpClient> {
     ): TClient;
 }
 
+/**
+ * Represents the options for configuring an `IHttpClient` instance.
+ *
+ * @template TClient - The type of the `IHttpClient` instance to be configured.
+ */
 export interface HttpClientOptions<TClient extends IHttpClient = IHttpClient> {
+    /** The base URI for the `IHttpClient` instance. */
     baseUri?: string;
+
+    /** The default scopes to be used by the `IHttpClient` instance. */
     defaultScopes?: string[];
+
+    /** The constructor for the `TClient` type. */
     ctor?: HttpClientConstructor<TClient>;
+
+    /** A callback function that is called when a new `TClient` instance is created. */
     onCreate?: (client: TClient) => void;
+
+    /** The request handler to be used by the `IHttpClient` instance. */
     requestHandler?: IHttpRequestHandler<HttpClientRequestInitType<TClient>>;
+
+    /** The response handler to be used by the `IHttpClient` instance. */
     responseHandler?: IHttpResponseHandler<HttpClientRequestInitType<TClient>>;
 }
 
+/**
+ * Utility type that extracts the request init type from an `IHttpClient` implementation.
+ * This is useful for ensuring type safety when configuring an `IHttpClient` instance.
+ *
+ * @template T - The type of the `IHttpClient` implementation.
+ * @returns The request init type for the `IHttpClient` implementation.
+ */
 export type HttpClientRequestInitType<T extends IHttpClient> =
     T extends IHttpClient<infer U> ? U : never;
 
@@ -117,7 +154,7 @@ export class HttpClientConfigurator<TClient extends IHttpClient>
         name: string,
         args: string | HttpClientOptions<T> | HttpClientOptions<T>['onCreate'],
     ): HttpClientConfigurator<TClient> {
-        const argFn = typeof args === 'string' ? (x: T) => (x.uri = String(args)) : args;
+        const argFn = typeof args === 'string' ? ({ baseUri: args } as HttpClientOptions<T>) : args;
         const options = typeof argFn === 'function' ? { onCreate: argFn } : argFn;
         this._clients[name] = {
             ...this._clients[name],

package/src/errors.ts

@@ -15,7 +15,9 @@ export class HttpResponseError<TResponse = Response> extends Error {
 
 /**
  * Represents an error that occurs when handling a JSON response in an HTTP request.
- * @template TType - The type of the data contained in the response.
+ * Extends the base `HttpResponseError` class.
+ *
+ * @template TType - The type of the data associated with the error.
  * @template TResponse - The type of the HTTP response.
  */
 export class HttpJsonResponseError<
@@ -24,6 +26,14 @@ export class HttpJsonResponseError<
 > extends HttpResponseError<TResponse> {
     static Name = 'HttpJsonResponseError';
     public readonly data?: TType;
+
+    /**
+     * Creates a new instance of `HttpJsonResponseError`.
+     *
+     * @param message - The error message.
+     * @param response - The HTTP response associated with the error.
+     * @param options - Additional options for the error, including the associated data.
+     */
     constructor(message: string, response: TResponse, options?: ErrorOptions & { data?: TType }) {
         super(message, response, options);
         this.name = HttpJsonResponseError.Name;

package/src/lib/client/client-msal.ts

@@ -2,30 +2,75 @@ import type { Observable } from 'rxjs';
 import type { FetchRequestInit, FetchRequest, FetchResponse } from '.';
 import { HttpClient } from './client';
 
-/** Extends request init with scope  */
+/**
+ * Extends the `FetchRequest` type with an optional `scopes` property, which is an array of strings representing the scopes to be used for the request.
+ * This type is used to represent a request that requires authentication using the MSAL (Microsoft Authentication Library) library.
+ */
 type MsalFetchRequest = FetchRequest & { scopes?: string[] };
+
+/**
+ * Extends the `FetchRequestInit` type with an optional `scopes` property, which is an array of strings representing the scopes to be used for the request.
+ * This type is used to represent a request that requires authentication using the MSAL (Microsoft Authentication Library) library.
+ *
+ * @template TReturn - The type of the response object. Defaults to `unknown`.
+ * @template TRequest - The type of the request object. Defaults to `FetchRequest`.
+ * @template TResponse - The type of the response object. Defaults to `Response`.
+ */
 type MsalFetchRequestInit<
     TReturn = unknown,
     TRequest = FetchRequest,
     TResponse = FetchResponse,
 > = FetchRequestInit<TReturn, TRequest, TResponse> & Pick<MsalFetchRequest, 'scopes'>;
 
-/** Default Client for MSAL */
+/**
+ * Extends the `HttpClient` class to provide MSAL (Microsoft Authentication Library) authentication support.
+ *
+ * The `HttpClientMsal` class is responsible for handling requests that require authentication using the MSAL library.
+ * It extends the `HttpClient` class and adds the following functionality:
+ *
+ * - `defaultScopes`: An array of strings representing the default scopes to be used for all requests, unless overridden in the request object.
+ * - `fetch$`: Overrides the `fetch$` method of the `HttpClient` class to add MSAL authentication support. It takes an optional `MsalFetchRequestInit` object, which can include the `scopes` property to specify the scopes to be used for the request.
+ *   - If `scopes` is provided in the `MsalFetchRequestInit` object, it will be used in addition to the `defaultScopes`.
+ *   - If `scopes` is not provided, only the `defaultScopes` will be used.
+ *
+ * @template TRequest - The type of the request object. Defaults to `MsalFetchRequest`.
+ * @template TResponse - The type of the response object. Defaults to `FetchResponse`.
+ */
 export class HttpClientMsal<
     TRequest extends MsalFetchRequest = MsalFetchRequest,
     TResponse extends FetchResponse = FetchResponse,
 > extends HttpClient<TRequest, TResponse> {
-    /** Scope that will be applied to all request if no scope is provided in request object */
+    /**
+     * An array of default scopes to be used for all requests, unless overridden in the request object.
+     * This property is used by the `HttpClientMsal` class to add MSAL authentication support to requests.
+     */
     public defaultScopes: string[] = [];
 
-    /** @inheritdoc */
-    fetch$<T = TResponse>(
+    /**
+     * Fetches a resource from the specified path, with optional MSAL authentication scopes.
+     *
+     * This method extends the `HttpClient.fetch$` method to add support for MSAL authentication.
+     * If `init.scopes` is provided, it will be used in addition to the `defaultScopes` defined in the `HttpClientMsal` class.
+     * If `init.scopes` is not provided, only the `defaultScopes` will be used for the request.
+     *
+     * @overrides HttpClient.fetch$
+     *
+     * @param path - The path to the resource to fetch.
+     * @param init - An optional `MsalFetchRequestInit` object that can include the `scopes` property.
+     * @returns An `Observable` that emits the fetched resource.
+     */
+    public fetch$<T = TResponse>(
         path: string,
         init?: MsalFetchRequestInit<T, TRequest, TResponse>,
     ): Observable<T> {
+        /**
+         * Merges the default scopes defined in the `HttpClientMsal` class with the scopes provided in the `init` parameter, if any.
+         * This ensures that the request includes the necessary scopes for MSAL authentication.
+         */
         const args = Object.assign(init || {}, {
             scopes: this.defaultScopes.concat(init?.scopes || []),
         }) as FetchRequestInit<T, TRequest, TResponse>;
+
         return super._fetch$(path, args);
     }
 }