@equinor/fusion-framework-module-http 7.0.8 → 8.0.0

package/dist/types/configurator.d.ts

@@ -5,10 +5,13 @@ 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.
+ * @template TResponse - The type of the response object used by the `IHttpClient` instance.
  * @property {IHttpRequestHandler<TInit>} requestHandler - The request handler to be used by the `IHttpClient` instance.
+ * @property {IHttpResponseHandler<TResponse>} [responseHandler] - The response handler to be used by the `IHttpClient` instance.
  */
-interface HttpClientConstructorOptions<TInit extends FetchRequest> {
+interface HttpClientConstructorOptions<TInit extends FetchRequest, TResponse = Response> {
     requestHandler: IHttpRequestHandler<TInit>;
+    responseHandler?: IHttpResponseHandler<TResponse>;
 }
 /**
  * Represents a constructor for an `IHttpClient` instance.
@@ -19,12 +22,15 @@ interface HttpClientConstructorOptions<TInit extends FetchRequest> {
  * @returns A new instance of the `TClient` type.
  */
 interface HttpClientConstructor<TClient extends IHttpClient> {
-    new (uri: string, options: HttpClientConstructorOptions<HttpClientRequestInitType<TClient>>): TClient;
+    new (uri: string, options: HttpClientConstructorOptions<HttpClientRequestInitType<TClient>, HttpClientResponseType<TClient>>): TClient;
 }
 /**
- * Represents the options for configuring an `IHttpClient` instance.
+ * Configures how the provider creates a named `IHttpClient` instance.
  *
- * @template TClient - The type of the `IHttpClient` instance to be configured.
+ * Use these options to define a base URL, MSAL scopes, shared request or response handlers,
+ * a custom client constructor, or per-instance setup through `onCreate`.
+ *
+ * @template TClient - The client type created from this configuration.
  */
 export interface HttpClientOptions<TClient extends IHttpClient = IHttpClient> {
     /** The base URI for the `IHttpClient` instance. */
@@ -38,7 +44,7 @@ export interface HttpClientOptions<TClient extends IHttpClient = IHttpClient> {
     /** 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>>;
+    responseHandler?: IHttpResponseHandler<HttpClientResponseType<TClient>>;
 }
 /**
  * Utility type that extracts the request init type from an `IHttpClient` implementation.
@@ -49,60 +55,77 @@ export interface HttpClientOptions<TClient extends IHttpClient = IHttpClient> {
  */
 export type HttpClientRequestInitType<T extends IHttpClient> = T extends IHttpClient<infer U> ? U : never;
 /**
- * Instance for configuring http client
- * @template TClient base type of client that the provider will create
+ * Utility type that extracts the response type from an `IHttpClient` implementation.
+ * This is useful for ensuring type safety when configuring response handlers for an `IHttpClient` instance.
+ *
+ * @template T - The type of the `IHttpClient` implementation.
+ * @returns The response type for the `IHttpClient` implementation.
+ */
+export type HttpClientResponseType<T extends IHttpClient> = T extends IHttpClient<infer _TRequest, infer TResponse> ? TResponse : never;
+/**
+ * Registers and looks up named HTTP client configurations for the HTTP module.
+ *
+ * Each named configuration can later be turned into a fresh client instance by the provider.
+ *
+ * @template TClient - The base client type the provider creates.
  */
 export interface IHttpClientConfigurator<TClient extends IHttpClient = IHttpClient> {
     readonly clients: Record<string, HttpClientOptions<TClient>>;
     readonly defaultHttpClientCtor: HttpClientConstructor<TClient>;
     readonly defaultHttpRequestHandler: IHttpRequestHandler<HttpClientRequestInitType<TClient>>;
     /**
-     * Configure a client with arguments
-     * @param name name of the client
-     * @param args option that are used cor creating a client
+     * Registers or updates a named client configuration.
+     * @param name - The client key used later with `createClient(name)`.
+     * @param args - The configuration used when creating a client instance.
+     * @returns The configurator so registrations can be chained.
      * @example
      * ```ts
-     * configurator.http.configureClient('foo',{
-     *   baseUri: 'https://foo.bar',
-     *   defaultScopes: ['foobar/.default']
+     * configurator.http.configureClient('catalog', {
+     *   baseUri: 'https://api.example.com',
+     *   defaultScopes: ['api://catalog-api/.default'],
      * });
      * ```
      */
     configureClient<T extends TClient>(name: string, args: HttpClientOptions<T>): IHttpClientConfigurator<TClient>;
     /**
-     * Configure a simple client by name to an endpoint
-     * @param name name of the client
-     * @param uri base endpoint for the client
+     * Registers a named client with only a base URI.
+     * @param name - The client key used later with `createClient(name)`.
+     * @param uri - The base endpoint for the client.
+     * @returns The configurator so registrations can be chained.
      */
     configureClient(name: string, uri: string): IHttpClientConfigurator<TClient>;
     /**
-     * Creates a client with callback configuration
-     * @param name name of the client
-     * @param onCreate callback when a client is created
+     * Registers a named client using only an `onCreate` callback.
+     * @param name - The client key used later with `createClient(name)`.
+     * @param onCreate - The callback that runs for every created client instance.
+     * @returns The configurator so registrations can be chained.
+     * @example
      * ```ts
-     * configurator.http.configureClient('foo',(client) => {
+     * configurator.http.configureClient('catalog', (client) => {
      *   client.requestHandler.add('logger', (request) => console.log(request));
      * });
      * ```
      */
     configureClient<T extends TClient>(name: string, onCreate: (client: T) => void): HttpClientConfigurator<TClient>;
     /**
-     * Check if there is a configuration for provided name
+     * Checks whether a named client configuration exists.
+     * @param name - The client key to check.
+     * @returns `true` when a configuration exists for the key.
      */
     hasClient(name: string): boolean;
 }
 /** @inheritdoc */
 export declare class HttpClientConfigurator<TClient extends IHttpClient> implements IHttpClientConfigurator<TClient> {
     protected _clients: Record<string, HttpClientOptions<TClient>>;
-    /** Get a clone of all configured clients */
+    /** Gets a shallow clone of all named client configurations. */
     get clients(): Record<string, HttpClientOptions<TClient>>;
-    /** default class for creation of http clients */
+    /** Default constructor used when a client configuration does not provide `ctor`. */
     readonly defaultHttpClientCtor: HttpClientConstructor<TClient>;
-    /** default request handler for http clients, applied on creation */
+    /** Default request handler pipeline cloned into each created client instance. */
     readonly defaultHttpRequestHandler: HttpRequestHandler<HttpClientRequestInitType<TClient>>;
     /**
-     * Create a instance of http configuration
-     * @param client defaultHttpRequestHandler
+     * Creates a configurator with the default client constructor.
+     * @param client - The default client constructor used when `ctor` is not configured per client.
      */
     constructor(client: HttpClientConstructor<TClient>);
     /** @inheritdoc */

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

@@ -126,15 +126,15 @@ export declare class HttpClient<TRequest extends FetchRequest = FetchRequest, TR
      * @returns A `StreamResponse` that emits `ServerSentEvent<T>` objects as they are received from the server.
      *
      * @example
-     * const sse$ = httpClient.sse(
-     *  '/events',
-     *  { method: 'POST', body: JSON.stringify({ prompt: 'tell me a joke' }) },
-     *  { eventFilter: ['message'] }
+     * const sse$ = httpClient.sse$(
+     *   '/events',
+     *   { method: 'POST', body: JSON.stringify({ prompt: 'tell me a joke' }) },
+     *   { eventFilter: ['message'] },
      * );
      * sse$.subscribe({
-     *  next: (event) => console.log(event),
-     *  error: (err) => console.error(err),
-     *  complete: () => console.log('Completed'),
+     *   next: (event) => console.log(event),
+     *   error: (err) => console.error(err),
+     *   complete: () => console.log('Completed'),
      * });
      */
     sse$<T = unknown>(path: string, args?: FetchRequestInit<ServerSentEvent<T>, TRequest, TResponse> | null, options?: Omit<SseSelectorOptions<T>, 'abortSignal'>): StreamResponse<ServerSentEvent<T>>;

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

@@ -3,4 +3,5 @@ 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 * from './types';

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

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

package/dist/types/module.d.ts

@@ -23,23 +23,32 @@ export type HttpMsalModule = Module<'http', IHttpClientProvider<HttpClientMsal>,
     MsalModule
 ]>;
 /**
- * HTTP module with MSAL authentication.
+ * Default HTTP module definition for Fusion Framework applications.
+ *
+ * The module uses `HttpClientMsal` as the default client implementation and,
+ * when the auth module is available, installs a request handler that can acquire
+ * bearer tokens for scoped requests.
  */
 export declare const module: HttpMsalModule;
 /**
- * Configures the HTTP module with MSAL authentication.
+ * Creates a module configurator for the HTTP module.
+ *
+ * Use this when you need lower-level access to the module configuration callback,
+ * for example when registering several named clients in one setup step.
+ *
+ * @param configure - The callback that receives the HTTP module configuration.
+ * @returns A module configurator for the HTTP module.
  */
 export declare const configureHttp: <TRef = unknown>(configure: (config: ModuleConfigType<HttpMsalModule>, ref?: TRef) => void) => IModuleConfigurator<HttpMsalModule, TRef>;
 /**
- * Configures the HTTP client with MSAL authentication.
+ * Creates a module configurator that registers one named HTTP client.
  *
- * 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.
+ * This is the convenience API for the common case where a setup step only needs to
+ * register one client with `baseUri`, `defaultScopes`, handlers, or a custom constructor.
  *
- * @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.
+ * @param name - The client key used later with `createClient(name)`.
+ * @param args - The named client configuration.
+ * @returns A module configurator that registers the named client.
  */
 export declare const configureHttpClient: <TRef = unknown>(name: string, args: HttpClientOptions<HttpClientMsal>) => IModuleConfigurator<HttpMsalModule, TRef>;
 /**

package/dist/types/provider.d.ts

@@ -4,15 +4,19 @@ import type { IHttpRequestHandler } from './lib/operators';
 import type { IHttpClient } from './lib/client';
 import { BaseModuleProvider } from '@equinor/fusion-framework-module/provider';
 /**
- * Exception thrown when a client cannot be found.
+ * Thrown when `createClient(name)` is called with an unknown client key.
  *
- * This error is typically used to indicate that a requested client instance
- * does not exist or cannot be located within the current context.
- *
- * @extends {Error}
+ * This is only used when the provided string is neither a registered client name
+ * nor an absolute `http:` or `https:` URL.
  */
 export declare class ClientNotFoundException extends Error {
 }
+/**
+ * Creates fresh HTTP client instances from named or ad-hoc configuration.
+ *
+ * A provider can create clients from registered names, inline `HttpClientOptions`,
+ * or absolute URLs treated as ad-hoc `baseUri` values.
+ */
 export interface IHttpClientProvider<TClient extends IHttpClient = IHttpClient> {
     /**
      * The default HTTP request handler used by the HttpClientProvider.
@@ -33,13 +37,17 @@ export interface IHttpClientProvider<TClient extends IHttpClient = IHttpClient>
     createClient(key: string): TClient;
     createClient(key: HttpClientOptions<TClient>): TClient;
     /**
-     * Class cast creation of custom client
+     * Creates a client instance and casts it to a custom HTTP client type.
+     *
+     * This is most useful when the named client configuration uses a custom `ctor`
+     * that extends `HttpClient` with domain-specific methods.
      * @example
      * ```ts
-     * config.http.configureClient('foobar', (client) => {
-     *   client.ctor = MyClient;
-     *   client.uri = 'https://foobar.com';
+     * config.http.configureClient('foobar', {
+     *   ctor: MyClient,
+     *   baseUri: 'https://foobar.com',
      * });
+     * ```
      */
     createCustomClient<T extends HttpClient>(key: string): T;
 }
@@ -62,7 +70,7 @@ export declare class HttpClientProvider<TClient extends IHttpClient = IHttpClien
      */
     hasClient(key: string): boolean;
     /**
-     * Creates a new HTTP client instance with the specified configuration.
+     * Creates a fresh HTTP client instance from a named or ad-hoc configuration.
      *
      * @param keyOrConfig - The key or configuration object for the HTTP client.
      * @returns The created HTTP client instance.
@@ -72,18 +80,14 @@ export declare class HttpClientProvider<TClient extends IHttpClient = IHttpClien
      * 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 method applies `baseUri`, `defaultScopes`, `requestHandler`, `responseHandler`,
+     * a custom `ctor` when configured, and finally runs `onCreate` for the newly created instance.
      *
      * The created HTTP client instance is returned.
      */
     createClient(keyOrConfig: string | HttpClientOptions<TClient>): TClient;
     /**
-     * Creates a new HTTP client instance with the specified configuration.
+     * Creates a client instance and returns it as the requested custom client type.
      *
      * @param key - The key of the pre-configured HTTP client to create.
      * @returns The created HTTP client instance, cast to the specified type `T`.
@@ -98,8 +102,9 @@ export declare class HttpClientProvider<TClient extends IHttpClient = IHttpClien
     /**
      * 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.
+     * If a string is provided, it is treated as either a pre-configured client key or,
+     * when it is an absolute `http:` or `https:` URL, as an ad-hoc `baseUri`.
+     * If an `HttpClientOptions` object is provided, it is used directly 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.

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "7.0.8";
+export declare const version = "8.0.0";

package/docs/client-configuration.md

@@ -0,0 +1,175 @@
+# Configure HTTP Clients
+
+Use HTTP client configuration when your application talks to the same backend more than once and you want one place to define base URLs, MSAL scopes, headers, and transport behavior.
+
+The main configuration APIs are:
+
+- `configureHttpClient(name, options)` for one named client
+- `configureHttp(...)` for lower-level module configuration
+- `createClient(name)` to create a fresh client instance from a named configuration
+- `createCustomClient<T>(name)` to create a custom client class with the same configuration
+
+## Named Clients vs Ad-Hoc Clients
+
+| Use case | API | Why |
+| --- | --- | --- |
+| One backend used throughout the app | `configureHttpClient(name, options)` | Keeps base URL, scopes, and shared behavior in one place |
+| Several clients configured together | `configureHttp(...)` | Useful when a module or setup step owns multiple backends |
+| One-off call to a specific base URL | `createClient({ baseUri })` | Useful for inline or temporary configuration |
+| One-off call to an absolute URL | `createClient('https://api.example.com')` | Useful when the URL itself is the configuration |
+
+> **Fusion app developers:** Higher-level frameworks like `@equinor/fusion-framework-app` can auto-register named clients from other sources (e.g. application config endpoints or service discovery) before your code runs. See the [`@equinor/fusion-framework-app` README](../../app/README.md) for details on how clients are registered at the app level and which source takes priority.
+
+## Quick Start
+
+```typescript
+configurator.configureHttpClient('catalog', {
+  baseUri: '/api/catalog',
+  defaultScopes: ['api://catalog-api/.default'],
+  onCreate: (client) => {
+    client.requestHandler.setHeader('X-App-Name', 'portal');
+  },
+});
+
+const client = framework.modules.http.createClient('catalog');
+const items = await client.json('/items');
+```
+
+This pattern is the normal entry point for application code.
+
+## Configuration Options
+
+| Option | What it controls |
+| --- | --- |
+| `baseUri` | Base URL used to resolve request paths. Relative values are resolved against `window.location.origin`. |
+| `defaultScopes` | Default MSAL scopes used by `HttpClientMsal` requests. |
+| `ctor` | Custom client constructor when you want domain-specific client methods. |
+| `onCreate` | Callback that runs for every newly created client instance. |
+| `requestHandler` | Initial request handler pipeline cloned into created clients. |
+| `responseHandler` | Initial response handler pipeline passed into created clients. |
+
+## Use `onCreate` For Shared Client Behavior
+
+`onCreate` is the main place to attach behavior that every fresh client instance should start with.
+
+```typescript
+configurator.configureHttpClient('catalog', {
+  baseUri: '/api/catalog',
+  onCreate: (client) => {
+    client.requestHandler.setHeader('X-Feature', 'catalog');
+    client.responseHandler.add('reject-unauthorized', (response) => {
+      if (response.status === 401) {
+        throw new Error('Unauthorized');
+      }
+    });
+  },
+});
+```
+
+Use this for headers, logging, validation, transport guards, and response policies.
+
+## MSAL Scope Behavior
+
+When the auth module is available, the HTTP module can acquire an access token before sending the request.
+
+- `defaultScopes` come from the configured client
+- per-request `scopes` are appended to `defaultScopes`
+- token acquisition only happens when the final scope list is non-empty
+
+```typescript
+await client.json('/items', {
+  scopes: ['api://catalog-admin/.default'],
+});
+```
+
+That request uses both the configured `defaultScopes` and the request-specific scopes.
+
+## Direct Module Integration
+
+If you are configuring modules directly instead of using higher-level framework helpers, use the package exports.
+
+```typescript
+import {
+  configureHttp,
+  configureHttpClient,
+} from '@equinor/fusion-framework-module-http';
+
+configurator.addConfig(configureHttpClient('catalog', {
+  baseUri: '/api/catalog',
+}));
+
+configurator.addConfig(configureHttp((http) => {
+  http.configureClient('search', {
+    baseUri: '/api/search',
+  });
+}));
+```
+
+Use `configureHttpClient(...)` when you only need one named client. Use `configureHttp(...)` when a module setup step owns several client registrations.
+
+## Ad-Hoc Clients
+
+The provider also supports one-off client creation without a named configuration.
+
+```typescript
+const inlineClient = framework.modules.http.createClient({
+  baseUri: '/api/search',
+});
+
+const urlClient = framework.modules.http.createClient('https://api.example.com');
+```
+
+If the string passed to `createClient()` is not a configured key but is an absolute `http:` or `https:` URL, the provider treats it as a `baseUri`.
+
+## Custom Client Classes
+
+Use `ctor` when you want to wrap the shared transport behavior in domain-specific methods.
+
+```typescript
+import { HttpClient } from '@equinor/fusion-framework-module-http/client';
+
+class ApiClient extends HttpClient {
+  getHealth(): Promise<{ status: string }> {
+    return this.json('/health');
+  }
+}
+
+configurator.configureHttpClient('api', {
+  baseUri: '/api',
+  ctor: ApiClient,
+});
+
+const client = framework.modules.http.createCustomClient<ApiClient>('api');
+const health = await client.getHealth();
+```
+
+## What `createClient()` Does
+
+Each call to `createClient()` creates a fresh client instance.
+
+- the client starts with its configured `baseUri`
+- `defaultScopes` are assigned to the client instance
+- `requestHandler` and `responseHandler` configuration is applied to that instance
+- `onCreate` runs for that specific instance
+
+This matters because headers and handlers added to one created client do not leak into the next created client from the same named configuration.
+
+## Missing Clients And Safe Lookup
+
+Use `hasClient(name)` when a client configuration may be optional.
+
+```typescript
+if (framework.modules.http.hasClient('catalog')) {
+  const client = framework.modules.http.createClient('catalog');
+  await client.json('/items');
+}
+```
+
+If you call `createClient(name)` with an unknown key, the provider throws `ClientNotFoundException`.
+
+## Rule Of Thumb
+
+- use named clients for stable backends
+- use `onCreate` for shared transport behavior
+- use `ctor` when you want domain-specific methods
+- use ad-hoc clients only when the configuration is truly local

package/docs/observable-patterns.md

@@ -0,0 +1,103 @@
+# Observable Patterns
+
+The observable API exposes the same HTTP transport pipeline as the promise API, but in a form that composes naturally with RxJS.
+
+Use `fetch$()`, `json$()`, `blob$()`, and `sse$()` when your request depends on other streams, needs cancellation by unsubscribe, or should participate in a larger RxJS workflow.
+
+## Promise Methods vs Observable Methods
+
+| Need | Recommended API |
+| --- | --- |
+| One request and one result | `fetch()` or `json()` |
+| RxJS composition | `fetch$()` or `json$()` |
+| Automatic cancellation when input changes | `fetch$()` or `json$()` with `switchMap` |
+| Observing transport activity | `request$`, `response$`, and the observable request methods |
+| Streaming server events | `sse$()` |
+
+Promise methods are implemented with `firstValueFrom(...)` on the corresponding observable method. That means both forms share the same underlying request pipeline.
+
+## Core Observable Behavior
+
+- observable request methods are cold
+- nothing is sent until you subscribe
+- unsubscribing aborts the underlying fetch
+- `client.abort()` cancels every in-flight request started by that client instance
+- `request$` and `response$` are per-client streams, not global streams
+
+## Pattern: Request From Another Stream
+
+Use `switchMap` when a new upstream value should replace the previous in-flight request.
+
+```typescript
+import { switchMap } from 'rxjs/operators';
+
+const item$ = selectedId$.pipe(
+  switchMap((id) => client.json$(`/items/${id}`)),
+);
+```
+
+This pattern works well for route parameters, selected rows, debounced search terms, and refresh triggers.
+
+## Pattern: Observe Transport Activity
+
+Each client instance exposes `request$` and `response$` so you can observe transport behavior alongside your result stream.
+
+```typescript
+const requestLog = client.request$.subscribe((request) => {
+  console.debug('request', request.method, request.uri);
+});
+
+const responseLog = client.response$.subscribe((response) => {
+  console.debug('response', response.status, response.url);
+});
+```
+
+Use these streams for diagnostics, telemetry, debugging operators, or building test helpers.
+
+## Pattern: Cancel By Unsubscribing
+
+Observable requests are a good fit for component and service lifecycles because cancellation is built in.
+
+```typescript
+const subscription = client.json$('/items').subscribe({
+  next: console.log,
+  error: console.error,
+});
+
+subscription.unsubscribe();
+```
+
+After unsubscribe, the client aborts the underlying fetch.
+
+## Pattern: Reuse Parsing With Selectors
+
+Selectors work well with observable request methods because they separate transport from parsing.
+
+```typescript
+const user$ = client.fetch$('/users/42', {
+  selector: userSelector,
+});
+```
+
+This lets you keep parsing logic reusable while still composing the request with RxJS operators.
+
+## Pattern: Use The Right Layer For The Job
+
+For most advanced flows, the HTTP module works best when each layer has one responsibility.
+
+- use `fetch$()` or `json$()` for transport
+- use selectors for response parsing
+- use request and response handlers for cross-cutting transport behavior
+- use RxJS operators for orchestration and composition
+
+## Common Observable Workflows
+
+- a route parameter stream drives `json$()` with `switchMap`
+- a user action stream triggers `fetch$()` and `catchError`
+- a request is observed through `request$` for telemetry
+- a response is observed through `response$` for diagnostics
+- an SSE endpoint uses `sse$()` for incremental updates
+
+## Rule Of Thumb
+
+Start with `json()` if you just need the result of one request. Move to `json$()` or `fetch$()` when the request is part of a reactive workflow.