@equinor/fusion-framework-module-http 8.0.3 → 8.0.4

package/src/lib/client/client.ts

@@ -17,12 +17,12 @@ import type {
   StreamResponse,
 } from './types';
 
-import { HttpResponseError } from '../../errors';
+import { HttpResponseError } from '../../errors/index.js';
 import {
   createSseSelector,
   type ServerSentEvent,
   type SseSelectorOptions,
-} from '../selectors/sse-selector';
+} from '../selectors/create-sse-selector';
 
 /**
  * Configuration options for creating an `HttpClient` instance.
@@ -78,6 +78,7 @@ export class HttpClient<
 
   /**
    * A stream of requests that are about to be executed.
+   * @returns An `Observable` that emits each request before it is executed.
    */
   public get request$(): Observable<TRequest> {
     return this._request$.asObservable();
@@ -85,11 +86,17 @@ export class HttpClient<
 
   /**
    * A stream of responses that have been received.
+   * @returns An `Observable` that emits each response as it is received.
    */
   public get response$(): Observable<TResponse> {
     return this._response$.asObservable();
   }
 
+  /**
+   * Creates a new `HttpClient`.
+   * @param uri - The base URI used to resolve relative request paths.
+   * @param options - Optional request and response handlers.
+   */
   constructor(
     public uri: string,
     options?: Partial<HttpClientCreateOptions<TRequest, TResponse>>,
@@ -112,6 +119,7 @@ export class HttpClient<
   /**
    * Fetches data from the specified path and returns a stream response.
    *
+   * @template T - The expected shape of the fetched data.
    * @param path - The path to fetch data from.
    * @param args - Optional request initialization options, including a custom selector function.
    * @returns A stream response containing the fetched data.
@@ -126,6 +134,7 @@ export class HttpClient<
   /**
    * Fetches data from the specified path and returns a Promise containing the fetched data.
    *
+   * @template T - The expected shape of the fetched data.
    * @param path - The path to fetch data from.
    * @param args - Optional request initialization options, including a custom selector function.
    * @returns A Promise containing the fetched data.
@@ -137,7 +146,13 @@ export class HttpClient<
     return firstValueFrom(this.fetch$<T>(path, args));
   }
 
-  /** @deprecated */
+  /**
+   * @deprecated Use {@link fetch} instead.
+   * @template T - The expected shape of the fetched data.
+   * @param path - The path to fetch data from.
+   * @param args - Optional request initialization options, including a custom selector function.
+   * @returns A Promise containing the fetched data.
+   */
   public fetchAsync<T = TResponse>(
     path: string,
     args?: FetchRequestInit<T, TRequest, TResponse>,
@@ -148,6 +163,7 @@ export class HttpClient<
   /**
    * Fetches data from the specified path and returns a stream response containing the data in JSON format.
    *
+   * @template T - The expected shape of the parsed JSON data.
    * @param path - The path to fetch the data from.
    * @param args - Optional request initialization options, including a custom selector function and request body.
    *   - `body`: The request body, which will be automatically serialized to JSON if it's an object.
@@ -175,6 +191,7 @@ export class HttpClient<
   /**
    * Fetches data from the specified path and returns a Promise containing the fetched data in JSON format.
    *
+   * @template T - The expected shape of the parsed JSON data.
    * @param path - The path to fetch the data from.
    * @param args - Optional request initialization options, including a custom selector function and request body.
    *   - `body`: The request body, which will be automatically serialized to JSON if it's an object.
@@ -192,6 +209,7 @@ export class HttpClient<
   /**
    * Fetches a blob resource from the specified path and returns a stream response.
    *
+   * @template T - The expected shape of the fetched blob data.
    * @param path - The path to the blob resource.
    * @param args - Optional request initialization options, including a custom selector function.
    * @returns A stream response containing the fetched blob data.
@@ -216,6 +234,7 @@ export class HttpClient<
   /**
    * Fetches a blob from the specified path and returns a Promise that resolves to the blob result.
    *
+   * @template T - The expected shape of the fetched blob data.
    * @param path - The path to fetch the blob from.
    * @param args - Optional arguments for the fetch request, including request body, headers, and response type.
    * @returns A Promise that resolves to the blob result.
@@ -272,7 +291,13 @@ export class HttpClient<
     >);
   }
 
-  /** @deprecated */
+  /**
+   * @deprecated Use {@link json} instead.
+   * @template T - The expected shape of the parsed JSON data.
+   * @param path - The path to fetch the data from.
+   * @param args - Optional request initialization options, including a custom selector function and request body.
+   * @returns A Promise containing the fetched data in JSON format.
+   */
   public jsonAsync<T = unknown>(
     path: string,
     args?: FetchRequestInit<T, JsonRequest<TRequest>, TResponse>,
@@ -283,6 +308,8 @@ export class HttpClient<
   /**
    * Executes an HTTP request using the specified method and path.
    *
+   * @template T - The expected shape of the result.
+   * @template TMethod - The name of the `IHttpClient` method to invoke.
    * @param method - The HTTP method to use for the request, such as 'fetch', 'json', or 'blob'.
    * @param path - The path to the resource to fetch.
    * @param init - Optional request initialization options, including request body, headers, and response type.
@@ -308,10 +335,13 @@ export class HttpClient<
   /**
    * Fetches data from the specified path and returns an Observable that emits the response.
    *
+   * @template T - The expected shape of the emitted data.
    * @param path - The path to fetch the data from.
    * @param args - Optional arguments for the fetch request, including a response selector function, request body, headers, and response type.
    * @returns {Observable<T>} An Observable that emits the response data.
    *
+   * @throws {HttpResponseError} When the optional `selector` throws while transforming the response.
+   *
    * This method handles the following steps:
    * 1. Resolves the full URL by combining the base URI and the provided path.
    * 2. Prepares the request by passing it through the `requestHandler.process()` method.
@@ -325,6 +355,9 @@ export class HttpClient<
     args?: FetchRequestInit<T, TRequest, TResponse>,
   ): Observable<T> {
     const { selector, ...options } = args || {};
+    // `fromFetch` yields the raw fetch `Response`, but `responseHandler.process()` (called via
+    // `_prepareResponse`) expects the pipeline's generic `TResponse` shape — cast through
+    // `unknown` since the two are only compatible after that processing step.
     const response$ = of({
       ...options,
       path,
@@ -343,6 +376,7 @@ export class HttpClient<
 
       /** execute selector */
       switchMap((response) => {
+        // only run the selector when one was provided; otherwise pass the response through untouched
         if (selector) {
           try {
             return selector(response);
@@ -361,6 +395,8 @@ export class HttpClient<
       /** cancel request on abort signal */
       takeUntil(this._abort$),
     );
+    // The pipe above resolves to the per-call generic `T` (via the optional `selector`), but
+    // the observable's static type tracks the class-level `TResponse` — cast to the caller's `T`.
     return response$ as unknown as Observable<T>;
   }
 

package/src/lib/operators/{http-request-handler.ts → HttpRequestHandler.ts}

@@ -1,4 +1,4 @@
-import { ProcessOperators } from './process-operators';
+import { ProcessOperators } from './ProcessOperators';
 import { requestOperatorHeader } from './request-operator-header';
 
 import type { FetchRequest } from '../client';
@@ -22,7 +22,7 @@ export class HttpRequestHandler<T extends FetchRequest = FetchRequest> extends P
    */
   setHeader(key: string, value: string): HttpRequestHandler<T> {
     const operator = requestOperatorHeader<T>(key, value);
-    return this.set('header-' + key, operator) as HttpRequestHandler<T>;
+    return this.set(`header-${key}`, operator) as HttpRequestHandler<T>;
   }
 }
 

package/src/lib/operators/{http-response-handler.ts → HttpResponseHandler.ts}

@@ -1,4 +1,4 @@
-import { ProcessOperators } from './process-operators';
+import { ProcessOperators } from './ProcessOperators';
 
 /**
  * The `HttpResponseHandler` class extends the `ProcessOperators` class and is responsible for handling HTTP responses.

package/src/lib/operators/{process-operators.ts → ProcessOperators.ts}

@@ -32,6 +32,7 @@ export class ProcessOperators<T> implements IProcessOperators<T> {
    *                    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>>) {
+    // accept either a raw operators record or another IProcessOperators instance to clone from
     if (operators && 'operators' in operators) {
       this._operators = { ...operators.operators };
     } else {
@@ -47,6 +48,7 @@ export class ProcessOperators<T> implements IProcessOperators<T> {
    * @throws Error if an operator with the same key already exists.
    */
   add(key: string, operator: ProcessOperator<T>): ProcessOperators<T> {
+    // guard against silently overwriting an existing operator under the same key
     if (Object.keys(this._operators).includes(key))
       throw Error(`Operator [${key}] already defined`);
     return this.set(key, operator);
@@ -94,6 +96,7 @@ export class ProcessOperators<T> implements IProcessOperators<T> {
     if (!operators.length) {
       return of(request);
     }
+    // feed the request through each operator sequentially, keeping the previous value when one returns void
     return from(Object.values(this._operators)).pipe(
       mergeScan(
         // resolve current operator and return result or previous if void

package/src/lib/operators/{capitalize-request-method.operator.ts → capitalize-request-method-operator.ts}

@@ -1,4 +1,4 @@
-import { requestMethodCasing } from './fetch-request.schema';
+import { requestMethodCasing } from './fetch-request.schemas';
 import type { ProcessOperator } from './types';
 
 /**
@@ -14,7 +14,9 @@ export const capitalizeRequestMethodOperator =
 
     request.method = success ? data : request.method?.toUpperCase();
 
+    // surface schema validation issues as warnings when not running silently
     if (error && !options?.silent) {
+      // one warning per issue so callers can see exactly what failed to validate
       for (const e of error.issues) {
         console.warn(e.message);
       }

package/src/lib/operators/index.ts

@@ -1,8 +1,8 @@
-export { HttpRequestHandler } from './http-request-handler';
-export { HttpResponseHandler } from './http-response-handler';
-export { ProcessOperators } from './process-operators';
-export { capitalizeRequestMethodOperator } from './capitalize-request-method.operator';
-export { requestValidationOperator } from './request-validation.operator';
-export { sseMap } from './sse.operator';
+export { HttpRequestHandler } from './HttpRequestHandler';
+export { HttpResponseHandler } from './HttpResponseHandler';
+export { ProcessOperators } from './ProcessOperators';
+export { capitalizeRequestMethodOperator } from './capitalize-request-method-operator';
+export { requestValidationOperator } from './request-validation-operator';
+export { sseMap } from './sse-map.operator';
 
 export * from './types';

package/src/lib/operators/{request-validation.operator.ts → request-validation-operator.ts}

@@ -1,7 +1,7 @@
 import type { z } from 'zod';
 import type { ProcessOperator } from './types';
 import type { FetchRequest } from '../client/types';
-import { fetchRequestSchema } from './fetch-request.schema';
+import { fetchRequestSchema } from './fetch-request.schemas';
 
 /**
  * Validates the given request using the `requestInitSchema`.
@@ -42,6 +42,7 @@ export const requestValidationOperator =
       const result = schema.parse(request) as T;
       return parse ? result : void 0;
     } catch (error) {
+      // re-throw so callers relying on `parse` can react to validation failures directly
       if (parse) {
         throw error;
       }

package/src/lib/operators/{sse.operator.ts → sse-map.operator.ts}

@@ -4,7 +4,7 @@ import {
   createSseSelector,
   type ServerSentEvent,
   type SseSelectorOptions,
-} from '../selectors/sse-selector';
+} from '../selectors/create-sse-selector';
 
 /**
  * An operator function for handling Server-Sent Events (SSE) in an RxJS pipeline.
@@ -39,6 +39,7 @@ export const sseMap =
     options?: SseSelectorOptions<R>,
   ): OperatorFunction<T, ServerSentEvent<R>> =>
   (source) =>
+    // parse each raw Response into a stream of typed server-sent events
     source.pipe(switchMap(createSseSelector<R, T>(options)));
 
 export default sseMap;

package/src/lib/operators/types.ts

@@ -11,6 +11,7 @@ import type { FetchRequest } from '../client';
  * @param request The input request to be processed.
  * @returns The transformed request, `void`, or a Promise that resolves to the transformed request or `void`.
  */
+// biome-ignore lint/suspicious/noConfusingVoidType: `void` here relies on TypeScript's special-cased "void-returning callback accepts any return value" behavior for process operators \u2014 `undefined` would break assignability of operator functions that return a transformed request
 export type ProcessOperator<T, R = T> = (request: T) => R | void | Promise<R | void>;
 
 /**

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

@@ -10,8 +10,8 @@ import type { ResponseSelector, BlobResult } from '../client/types';
 export const blobSelector: ResponseSelector = async <TResponse extends Response = Response>(
   response: TResponse,
 ): Promise<BlobResult> => {
+  // treat any non-2xx response as a failure rather than attempting to read its body
   if (!response.ok) {
-    // Throw an error if the network response is not successful
     throw new Error('network response was not OK');
   }
 
@@ -21,6 +21,7 @@ export const blobSelector: ResponseSelector = async <TResponse extends Response
   }
 
   // Extract the filename from the 'content-disposition' header
+  // locate the segment carrying the filename directive; other directives (e.g. inline/attachment) are ignored
   const filename = response.headers
     .get('content-disposition')
     ?.split(';')
@@ -32,7 +33,7 @@ export const blobSelector: ResponseSelector = async <TResponse extends Response
     // Convert the response to a Blob and return the filename and Blob
     const blob = await response.blob();
     return { filename, blob };
-  } catch (err) {
+  } catch (_err) {
     // Throw an error if there's a problem parsing the response
     throw Error('failed to parse response');
   }

package/src/lib/selectors/{sse-selector.ts → create-sse-selector.ts}

@@ -2,7 +2,7 @@ import { EMPTY, from, fromEvent, type Observable } from 'rxjs';
 import { finalize, takeUntil } from 'rxjs/operators';
 
 import type { ResponseSelector } from '../client/types.js';
-import { ServerSentEventResponseError } from '../../errors.js';
+import { ServerSentEventResponseError } from '../../errors/index.js';
 
 /**
  * A type representing a function that parses a string into a specific data type.
@@ -139,31 +139,41 @@ async function* readStream<TData>(
 
   const decoder = new TextDecoder();
 
+  // keep reading chunks from the stream until the reader signals completion
   while (true) {
     const { done, value } = await reader.read();
+    // the underlying stream has ended, nothing more to read
     if (done) {
+      // exit the read loop rather than yielding any further events
       break;
     }
 
     const text = decoder.decode(value, { stream: true });
     const events = parseEvents<TData>(text, { dataParser: options?.dataParser });
+    // a chunk may contain multiple complete SSE events, emit each in turn
     for (const event of events) {
+      // a retry directive reconfigures the reconnection delay rather than being a data event
       if (event.retry) {
         await new Promise((resolve) =>
           setTimeout(resolve, Number.parseInt(event.retry ?? '300', 10)),
         );
+        // nothing to yield for a retry-only event
         continue;
       }
+      // heartbeat filtering is opt-in via the skipHeartbeats option
       if (skipHeartbeats) {
         // Skip comment-based heartbeats (no event, data, or id)
         if (!event.event && !event.data && !event.id) {
+          // this event carries no payload, so treat it as a heartbeat and skip it
           continue;
         }
         // Skip named heartbeat events (e.g., event: heartbeat or event: ping)
         if (event.event && ['heartbeat', 'ping'].includes(event.event)) {
+          // an explicitly named heartbeat/ping event should also be skipped
           continue;
         }
       }
+      // only emit events that pass the caller-provided event type filter, if any
       if (!eventFilter || (event.event && eventFilter.includes(event.event))) {
         yield event as ServerSentEvent<TData>;
       }
@@ -225,36 +235,43 @@ export const createSseSelector = <TData = unknown, TResponse extends Response =
   options?: SseSelectorOptions<TData>,
 ): SseSelector<TData, TResponse> => {
   return (response: TResponse): Observable<ServerSentEvent<TData>> => {
+    // an unsuccessful HTTP status means there is no valid SSE stream to read
     if (!response.ok) {
       throw new ServerSentEventResponseError(`HTTP error! Status: ${response.status}`, response);
     }
 
+    // a missing body means there is nothing to stream from
     if (!response.body) {
       throw new ServerSentEventResponseError('Response body is not readable', response);
     }
 
+    // guard against consuming a non-SSE response as if it were an event stream
     if (!response.headers.get('Content-Type')?.includes('text/event-stream')) {
       throw new ServerSentEventResponseError('Response is not a text/event-stream', response);
     }
 
     const reader = response.body.getReader();
 
-    return from(
-      readStream<TData>(reader, {
-        dataParser: options?.dataParser,
-        skipHeartbeats: options?.skipHeartbeats,
-        eventFilter: options?.eventFilter,
-      }),
-    ).pipe(
-      // Stop reading if the abort signal is triggered
-      takeUntil(options?.abortSignal ? fromEvent(options.abortSignal, 'abort') : EMPTY),
-      finalize(async () => {
-        // cancel just in case of a pre-mature exit
-        await reader.cancel().catch(() => {
-          /** ignore cancellation errors */
-        });
-        reader.releaseLock();
-      }),
+    return (
+      from(
+        readStream<TData>(reader, {
+          dataParser: options?.dataParser,
+          skipHeartbeats: options?.skipHeartbeats,
+          eventFilter: options?.eventFilter,
+        }),
+      )
+        // stop the stream on abort and always release the underlying reader when done
+        .pipe(
+          // Stop reading if the abort signal is triggered
+          takeUntil(options?.abortSignal ? fromEvent(options.abortSignal, 'abort') : EMPTY),
+          finalize(async () => {
+            // cancel just in case of a pre-mature exit
+            await reader.cancel().catch(() => {
+              /** ignore cancellation errors */
+            });
+            reader.releaseLock();
+          }),
+        )
     );
   };
 };

package/src/lib/selectors/index.ts

@@ -1,6 +1,6 @@
 export { jsonSelector } from './json-selector';
 export { blobSelector } from './blob-selector';
-export { createSseSelector } from './sse-selector';
+export { createSseSelector } from './create-sse-selector';
 
 export type { ResponseSelector } from '../client/types';
 export type {
@@ -8,4 +8,4 @@ export type {
   ServerSentEvent,
   SseSelector,
   SseSelectorOptions,
-} from './sse-selector';
+} from './create-sse-selector';

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

@@ -1,5 +1,5 @@
 import type { ResponseSelector } from '../client/types';
-import { HttpJsonResponseError } from '../../errors';
+import { HttpJsonResponseError } from '../../errors/index.js';
 
 /**
  * Asynchronously parses the JSON data from a given HTTP response.

package/src/module.ts

@@ -77,15 +77,18 @@ export const module: HttpMsalModule = {
     requireInstance,
   }): Promise<HttpClientProvider<HttpClientMsal>> => {
     const httpProvider = new HttpClientProvider(config);
+    // wire up an MSAL bearer-token handler only when the auth module is registered
     if (hasModule('auth')) {
       const authProvider = await requireInstance('auth');
       httpProvider.defaultHttpRequestHandler.set('MSAL', async (request) => {
         const { scopes = [] } = request;
+        // only attempt to acquire a token when the request actually declares scopes
         if (scopes.length) {
-          /** TODO should be try catch, check caller for handling */
+          /** TODO(#5143): should be try catch, check caller for handling */
           const accessToken = await authProvider.acquireAccessToken({
             request: { scopes },
           });
+          // without a token there's nothing to attach, fall through to the default request
           if (accessToken) {
             const headers = new Headers(request.headers);
             headers.set('Authorization', `Bearer ${accessToken}`);

package/src/provider.ts

@@ -9,14 +9,7 @@ import type { IHttpRequestHandler } from './lib/operators';
 import type { IHttpClient } from './lib/client';
 import { BaseModuleProvider } from '@equinor/fusion-framework-module/provider';
 import { version } from './version';
-
-/**
- * Thrown when `createClient(name)` is called with an unknown client key.
- *
- * This is only used when the provided string is neither a registered client name
- * nor an absolute `http:` or `https:` URL.
- */
-export class ClientNotFoundException extends Error {}
+import { ClientNotFoundException } from './errors/index.js';
 
 /**
  * Creates fresh HTTP client instances from named or ad-hoc configuration.
@@ -105,6 +98,10 @@ export class HttpClientProvider<TClient extends IHttpClient = IHttpClient>
     return this.config.defaultHttpRequestHandler;
   }
 
+  /**
+   * Creates a new `HttpClientProvider`.
+   * @param config - The configurator providing client definitions and defaults.
+   */
   constructor(protected config: IHttpClientConfigurator<TClient>) {
     super({
       version,
@@ -149,6 +146,7 @@ export class HttpClientProvider<TClient extends IHttpClient = IHttpClient>
     } = config as HttpClientOptions<TClient>;
     const options = { requestHandler, responseHandler };
     const instance = new ctor(baseUri || '', options) as TClient;
+    // attach the resolved default scopes onto the instance without overwriting other own properties
     Object.assign(instance, { defaultScopes });
     onCreate?.(instance as TClient);
     return instance as TClient;
@@ -157,6 +155,7 @@ export class HttpClientProvider<TClient extends IHttpClient = IHttpClient>
   /**
    * Creates a client instance and returns it as the requested custom client type.
    *
+   * @template T - The custom `HttpClient` implementation type to cast the created instance to.
    * @param key - The key of the pre-configured HTTP client to create.
    * @returns The created HTTP client instance, cast to the specified type `T`.
    *
@@ -167,6 +166,8 @@ export class HttpClientProvider<TClient extends IHttpClient = IHttpClient>
    * is configured to use a different implementation.
    */
   public createCustomClient<T extends HttpClient>(key: string): T {
+    // `createClient` always returns the provider's configured `HttpClient` implementation —
+    // cast through `unknown` to hand back the caller-requested implementation type `T`.
     return this.createClient(key) as unknown as T;
   }
 
@@ -179,15 +180,20 @@ export class HttpClientProvider<TClient extends IHttpClient = IHttpClient>
    *
    * @param keyOrConfig - The key or configuration object for the HTTP client.
    * @returns The resolved HTTP client configuration.
+   * @throws {ClientNotFoundException} When `keyOrConfig` is a string that is neither a registered
+   * client key nor a URL-like value.
    */
   protected _resolveConfig(
     keyOrConfig: string | HttpClientOptions<TClient>,
   ): HttpClientOptions<TClient> {
+    // a string may reference a registered client key or an ad-hoc URL; anything else is used as-is
     if (typeof keyOrConfig === 'string') {
       const config = this.config.clients[keyOrConfig];
+      // an absolute http(s) URL can be used directly as an ad-hoc baseUri
       if (!config && isURL(keyOrConfig)) {
         return { baseUri: keyOrConfig };
       } else if (!config && looksLikeURL(keyOrConfig)) {
+        // recover from a missing protocol instead of failing outright, but warn so it can be fixed
         console.warn(
           `[HttpClientProvider] "${keyOrConfig}" looks like a URL but is missing the http:// or https:// protocol. ` +
             `Treating it as "https://${keyOrConfig}". ` +

package/src/version.ts

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

package/tests/HttpClient.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { lastValueFrom } from 'rxjs';
 
-import { ClientNotFoundException, HttpClientProvider } from '../src';
+import { Errors, HttpClientProvider } from '../src';
 import { HttpClientConfigurator } from '../src/configurator';
 import { HttpClient, HttpClientMsal } from '../src/lib';
 import { HttpResponseHandler } from '../src/lib/operators';
@@ -99,7 +99,7 @@ describe('HttpClient', () => {
 
   it('should throw when a configured client cannot be found', () => {
     expect(() => provider.createClient('missing-client')).toThrowError(
-      new ClientNotFoundException('No registered http client for key [missing-client]'),
+      new Errors.ClientNotFoundException('No registered http client for key [missing-client]'),
     );
   });
 

package/tests/operators.test.ts

@@ -126,7 +126,11 @@ describe('sseMap', () => {
       },
     );
 
-    const events = await lastValueFrom(of(response).pipe(sseMap<{ key: string }>(), toArray()));
+    const events = await lastValueFrom(
+      of(response)
+        // parse the SSE stream and collect every emitted event into a single array
+        .pipe(sseMap<{ key: string }>(), toArray()),
+    );
 
     expect(events).toEqual([{ data: { key: 'value' } }]);
   });