@equinor/fusion-framework-module-http 8.1.0-next.0 → 8.1.1

package/src/lib/operators/sse-map.operator.ts

@@ -1,45 +0,0 @@
-import type { OperatorFunction } from 'rxjs';
-import { switchMap } from 'rxjs/operators';
-import {
-  createSseSelector,
-  type ServerSentEvent,
-  type SseSelectorOptions,
-} from '../selectors/create-sse-selector';
-
-/**
- * An operator function for handling Server-Sent Events (SSE) in an RxJS pipeline.
- *
- * @template R - The type of the parsed data from the SSE.
- * @template T - The type of the input `Response` object, defaults to `Response`.
- *
- * @param options - Configuration options for the SSE selector.
- *
- * @returns An `OperatorFunction` that transforms a stream of `Response` objects
- * into a stream of `ServerSentEvent` objects containing parsed data of type `R`.
- *
- * @example
- * ```typescript
- * import { sseMap } from '@equinor/fusion-framework-module-http/operators';
- * import { fromFetch } from 'rxjs/fetch';
- *
- * const response$ = fromFetch('https://example.com/sse', {
- *   method: 'GET',
- *   headers: {
- *     'Accept': 'text/event-stream',
- *   },
- * }).pipe(
- *   sseMap( { /* SSE selector options *\/ })
- * ).subscribe((event) => {
- *   console.log(event.data); // Process the parsed SSE data
- * });
- * ```
- */
-export const sseMap =
-  <R = unknown, T extends Response = Response>(
-    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

@@ -1,174 +0,0 @@
-import type { Observable, ObservableInput } 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`.
- */
-// 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>;
-
-/**
- * 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>;
-
-  /**
-   * Removes a process operator from the collection.
-   * @param key The key of the operator to remove.
-   * @returns The updated collection of process operators.
-   */
-  remove(key: string): 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> {}
-
-/**
- * Continues an HTTP request by resolving the given (already-processed) request into a response.
- *
- * @remarks
- * The terminal `next` passed to the outermost {@link HttpMiddleware} ultimately resolves to
- * `HttpClient._performFetch` — the same overridable seam the mock system replaces — so
- * middleware wraps around either the real network call or a mocked one transparently.
- *
- * @param uri - The fully resolved URL for the request.
- * @param init - The prepared `fetch` request options.
- * @returns The resulting `Response`, or an observable input of it.
- */
-export type HttpMiddlewareNext = (
-  uri: string,
-  init: RequestInit,
-) => Response | ObservableInput<Response>;
-
-/**
- * Continues to the next registered {@link HttpMiddleware}, or the network call itself,
- * always resolving to a `Response` regardless of how that next step actually produced it —
- * a short-circuited `Response`, a `Promise`, or an `Observable`.
- *
- * @param uri - The fully resolved URL for the request.
- * @param init - The prepared `fetch` request options.
- * @returns A promise of the resulting `Response`.
- */
-export type HttpMiddlewareContinuation = (uri: string, init: RequestInit) => Promise<Response>;
-
-/**
- * Wraps request execution to add cross-cutting behavior — retries, caching, telemetry,
- * circuit breaking — around the network call itself, rather than transforming the
- * request or response payload.
- *
- * @remarks
- * Unlike {@link ProcessOperator}, which transforms a value in a linear pipeline, a middleware
- * controls whether and how many times `next` runs: it can short-circuit by never calling
- * `next`, retry by calling it more than once, or recover from a rejection it throws.
- * Registered middleware compose in an "onion" — the first one registered is outermost, so it
- * sees the request first and the response last.
- *
- * @param uri - The fully resolved URL for the request.
- * @param init - The prepared `fetch` request options.
- * @param next - Continues to the next registered middleware, or the network call itself.
- * @returns The resulting `Response`, or an observable input of it.
- *
- * @example Retry once on a failed response
- * ```typescript
- * const retryOnce: HttpMiddleware = async (uri, init, next) => {
- *   const response = await next(uri, init);
- *   return response.ok ? response : next(uri, init);
- * };
- * ```
- */
-export type HttpMiddleware = (
-  uri: string,
-  init: RequestInit,
-  next: HttpMiddlewareContinuation,
-) => Response | ObservableInput<Response>;
-
-/**
- * Registers and composes {@link HttpMiddleware} into a single execution pipeline wrapping
- * the network call.
- */
-export interface IHttpMiddlewareHandler {
-  /**
-   * Gets the registered middleware, in registration order.
-   */
-  get middleware(): readonly HttpMiddleware[];
-
-  /**
-   * Registers a middleware, wrapping every middleware registered before it.
-   * @param middleware - The middleware to register.
-   * @returns The updated handler, for chaining.
-   */
-  use(middleware: HttpMiddleware): IHttpMiddlewareHandler;
-
-  /**
-   * Runs the registered middleware chain around a request, ending with `terminal`.
-   * @param uri - The fully resolved URL for the request.
-   * @param init - The prepared `fetch` request options.
-   * @param terminal - The innermost step the chain wraps, called when every middleware defers to `next`.
-   * @returns An observable of the resulting `Response`.
-   */
-  process(uri: string, init: RequestInit, terminal: HttpMiddlewareNext): Observable<Response>;
-}

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

@@ -1,42 +0,0 @@
-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<BlobResult> => {
-  // treat any non-2xx response as a failure rather than attempting to read its body
-  if (!response.ok) {
-    throw new Error('network response was not OK');
-  }
-
-  // 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
-  // locate the segment carrying the filename directive; other directives (e.g. inline/attachment) are ignored
-  const filename = response.headers
-    .get('content-disposition')
-    ?.split(';')
-    .find((n) => n.includes('filename='))
-    ?.replace('filename=', '')
-    ?.trim();
-
-  try {
-    // 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');
-  }
-};
-
-export default blobSelector;

package/src/lib/selectors/create-sse-selector.ts

@@ -1,279 +0,0 @@
-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/index.js';
-
-/**
- * A type representing a function that parses a string into a specific data type.
- *
- * @typeParam TData - The type of the parsed data. Defaults to `unknown` if not specified.
- * @param data - The string input to be parsed.
- * @returns The parsed data of type `TData`.
- */
-export type DataParser<TData = unknown> = (data: string) => TData;
-
-const defaultDataParser: DataParser = (data: string) => {
-  try {
-    return JSON.parse(data);
-  } catch {
-    return data;
-  }
-};
-
-/**
- * Represents a Server-Sent Event (SSE) with optional fields.
- */
-export type ServerSentEvent<TData = unknown> = {
-  id?: string;
-  event?: string;
-  data?: TData;
-  retry?: string;
-};
-
-/**
- * Parses a string containing Server-Sent Events (SSE) data into individual event objects.
- *
- * @template TData - The type of the parsed `data` field in the event.
- * @param text - The raw SSE data as a string, where events are separated by double newlines.
- * @param options - Optional configuration for parsing the events.
- * @param options.dataParser - A custom parser function for the `data` field. Defaults to JSON parsing,
- *                             falling back to returning the raw string if parsing fails.
- *
- * @returns A generator that yields `ServerSentEvent` objects parsed from the input string.
- *
- * @remarks
- * - Empty lines and events with no fields are ignored.
- * - If the `data` field cannot be parsed as JSON, it is returned as a plain string.
- * - Fields other than `data` are stored as strings in the resulting `ServerSentEvent` object.
- *
- * @example
- * ```typescript
- * const sseData = `
- * id: 1
- * event: message
- * data: {"key":"value"}
- *
- * id: 2
- * event: update
- * data: plain text
- * `;
- *
- * for (const event of parseEvents(sseData)) {
- *   console.log(event);
- * }
- * // Output:
- * // { id: "1", event: "message", data: { key: "value" } }
- * // { id: "2", event: "update", data: "plain text" }
- * ```
- */
-function* parseEvents<TData = unknown>(
-  text: string,
-  options?: { dataParser?: DataParser<TData> },
-): Generator<ServerSentEvent<TData>> {
-  // Split the input string into individual event strings using double newline as separator
-  const eventStrings = text.split('\n\n');
-
-  const dataParser = options?.dataParser || (defaultDataParser as DataParser<TData>);
-
-  // Iterate through each event string
-  for (const eventStr of eventStrings) {
-    // Skip empty event strings (after trimming whitespace)
-    if (!eventStr.trim()) continue;
-
-    // Split the event string into lines (fields) using single newline
-    const lines = eventStr.split('\n');
-
-    // Use reduce to process each line in the event string
-    const event = lines.reduce(
-      (event, line) => {
-        // Skip empty lines
-        if (!line) return event;
-
-        // Find the index of the first colon, which separates field name and value
-        const colonIndex = line.indexOf(':');
-
-        // Skip lines without a colon (invalid format)
-        if (colonIndex === -1) return event;
-
-        // Extract the field name (before colon) and trim whitespace
-        const field = line.slice(0, colonIndex).trim();
-        // Extract the field value (after colon) and trim whitespace
-        const value = line.slice(colonIndex + 1).trim();
-
-        // Handle the 'data' field specially, attempting JSON parsing
-        if (field === 'data') {
-          event.data = dataParser(value);
-        } else {
-          // For non-data fields, assign the value as a string to the event object
-          (event as Record<string, unknown>)[field] = value;
-        }
-
-        return event;
-      },
-      {} as ServerSentEvent<TData>,
-    );
-
-    // Only emit the event to the results if it has at least one field
-    if (Object.keys(event).length) {
-      yield event;
-    }
-  }
-}
-
-async function* readStream<TData>(
-  reader: ReadableStreamDefaultReader<Uint8Array>,
-  options?: {
-    dataParser?: DataParser<TData>;
-    skipHeartbeats?: boolean;
-    eventFilter?: string | string[];
-  },
-): AsyncGenerator<ServerSentEvent<TData>> {
-  const skipHeartbeats = !!options?.skipHeartbeats;
-
-  const eventFilter = options?.eventFilter
-    ? Array.isArray(options.eventFilter)
-      ? options.eventFilter
-      : [options.eventFilter]
-    : null;
-
-  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>;
-      }
-    }
-  }
-}
-
-/**
- * Options for configuring the SSE (Server-Sent Events) selector.
- */
-export type SseSelectorOptions<TData = unknown> = {
-  dataParser?: DataParser<TData>;
-  /**
-   * A string or an array of strings specifying the events to filter.
-   * Only events matching the filter will be processed. If not provided,
-   * all events will be processed.
-   */
-  eventFilter?: string | string[];
-
-  /**
-   * A boolean indicating whether to skip processing heartbeat events.
-   * Defaults to `false` if not specified.
-   */
-  skipHeartbeats?: boolean;
-
-  /**
-   * An `AbortSignal` that can be used to abort the SSE operation.
-   * Useful for managing the lifecycle of the SSE connection.
-   */
-  abortSignal?: AbortSignal | null;
-};
-
-/**
- * A type alias for selecting and transforming Server-Sent Events (SSE) from an HTTP response.
- *
- * @template TData - The type of the data contained within the Server-Sent Event. Defaults to `unknown`.
- * @template TResponse - The type of the HTTP response object. Defaults to `Response`.
- *
- * This selector is used to process and extract `ServerSentEvent<TData>` objects
- * from an HTTP `Response` object, enabling custom handling of SSE data streams.
- */
-export type SseSelector<TData = unknown, TResponse extends Response = Response> = ResponseSelector<
-  ServerSentEvent<TData>,
-  TResponse
->;
-
-/**
- * Transforms an SSE response into an Observable stream of parsed events.
- * @param response - The HTTP response with Content-Type: text/event-stream.
- * @param options - Optional configuration for event filtering and heartbeat handling.
- * @param options.eventFilter - Filter events by type (single string or array).
- * @param options.skipHeartbeats - Skip empty/heartbeat events if true.
- * @param options.dataParser - Custom parser for the data field.
- * @param options.abortSignal - Abort signal to cancel the stream.
- * @returns An Observable emitting parsed ServerSentEvent objects.
- * @throws ServerSentEventResponseError if response is invalid or stream fails.
- */
-export const createSseSelector = <TData = unknown, TResponse extends Response = 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,
-        }),
-      )
-        // 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();
-          }),
-        )
-    );
-  };
-};
-
-export default createSseSelector;

package/src/lib/selectors/index.ts

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

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

@@ -1,52 +0,0 @@
-import type { ResponseSelector } from '../client/types';
-import { HttpJsonResponseError } from '../../errors/index.js';
-
-/**
- * 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 const jsonSelector: ResponseSelector = async <
-  TType = unknown,
-  TResponse extends Response = Response,
->(
-  response: TResponse,
-): Promise<TType> => {
-  /** 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 });
-  }
-};
-
-export default jsonSelector;

package/src/mock/create-open-api-mock-middleware.ts

@@ -1,40 +0,0 @@
-import type { HttpMiddleware } from '../lib/operators/types';
-
-import { resolveOpenApiMockResponse, type OpenApiMockLike } from './resolve-open-api-mock-response';
-
-/**
- * Adapts an `OpenApiMock` into an {@link HttpMiddleware}, so
- * `configurator.http.addMiddleware(...)` fakes every matching request
- * straight from an OpenAPI document — no separate mock configurator needed.
- *
- * @remarks
- * A request that matches no operation in the document falls through to
- * `next`, so this composes with whatever else is registered — including the
- * real network call, or another middleware further down the chain. Because
- * `addMiddleware` wraps `_performFetch` rather than replacing it, the exact
- * same registration also fakes requests through any client this configurator
- * builds, so app config never has to branch on whether it's under test.
- *
- * @param openApiMock - Typically `createOpenApiMock(document)` from `@equinor/fusion-openapi-mock`.
- * @returns A middleware for {@link IHttpClientConfigurator.addMiddleware}.
- *
- * @example Fake every operation in a spec, straight from the document
- * ```typescript
- * import { createOpenApiMock } from '@equinor/fusion-openapi-mock';
- * import openapi from './openapi.json' with { type: 'json' };
- *
- * configurator.http.addMiddleware(createOpenApiMockMiddleware(createOpenApiMock(openapi)));
- * ```
- */
-export function createOpenApiMockMiddleware(openApiMock: OpenApiMockLike): HttpMiddleware {
-  return async (uri, init, next) => {
-    const response = await resolveOpenApiMockResponse(
-      openApiMock,
-      init.method ?? 'GET',
-      new URL(uri),
-    );
-    return response ?? next(uri, init);
-  };
-}
-
-export default createOpenApiMockMiddleware;