@obsidiane/meridiane 2.0.12 → 3.0.0

package/src/generators/models/schema-utils.js

@@ -1,6 +1,3 @@
-/** Hydra base schemas to ignore in safe `allOf` merges */
-const HYDRA_BASE_RE = /^Hydra(?:Item|Collection)BaseSchema$/;
-
 /**
  * Détermine si une valeur est un objet simple (non tableau)
  * @param {unknown} v
@@ -40,34 +37,3 @@ export function schemaNameFromRef($ref) {
   const match = String($ref ?? '').match(/^#\/components\/schemas\/([^/]+)$/);
   return match ? decodeJsonPointerSegment(match[1]) : undefined;
 }
-
-/**
- * Essaie d'aplatir un allOf en un objet unique.
- * Ignore HydraItemBaseSchema/HydraCollectionBaseSchema quand rencontré.
- * Retourne null si l'aplatissement n'est pas possible de manière sûre.
- * @param {any[]} schemas
- * @returns {any|null}
- */
-export function mergeAllOf(schemas) {
-  const out = {type: 'object', properties: {}, required: []};
-  for (const s of schemas) {
-    if (s.$ref) {
-      const ref = schemaNameFromRef(s.$ref);
-      if (ref && HYDRA_BASE_RE.test(ref)) {
-        continue;
-      }
-      return null;
-    }
-    if (s.type === 'object') {
-      for (const [name, property] of Object.entries(s.properties ?? {})) {
-        if (hasOwn(out.properties, name)) return null;
-        out.properties[name] = property;
-      }
-      if (Array.isArray(s.required)) out.required.push(...s.required);
-    } else {
-      return null;
-    }
-  }
-  out.required = [...new Set(out.required)];
-  return out;
-}

package/src/generators/models/type-resolver.js

@@ -53,7 +53,6 @@ function nonNegativeInteger(value) {
 export function createTypeResolver({
   dependencies = new Set(),
   typeNames = new Map(),
-  requiredMode = 'all',
   spec,
 } = {}) {
   const resolvingRefs = new Set();
@@ -81,11 +80,6 @@ export function createTypeResolver({
     }
   }
 
-  function resolveProperty(schema) {
-    const type = resolve(schema);
-    return requiredMode === 'spec' ? type : nullableType(type);
-  }
-
   function resolveDictionaryValue(additionalProperties, properties) {
     const additionalType = additionalProperties === true
       ? atomicType('any')
@@ -101,8 +95,8 @@ export function createTypeResolver({
     const requiredProperties = new Set(schema.required ?? []);
     const properties = Object.entries(schema.properties ?? {}).map(([key, propertySchema]) => ({
       key,
-      optional: requiredMode !== 'spec' || !requiredProperties.has(key),
-      type: resolveProperty(propertySchema),
+      optional: !requiredProperties.has(key),
+      type: resolve(propertySchema),
     }));
     const members = properties.map(({key, optional, type}) =>
       `${quoteKeyIfNeeded(key)}${optional ? '?' : ''}: ${type.code};`
@@ -224,17 +218,5 @@ export function createTypeResolver({
 
   return {
     typeOf: (schema) => resolve(schema).code,
-    nullableTypeOf: (schema) => nullableType(resolve(schema)).code,
   };
 }
-
-/**
- * Resolves an OpenAPI schema to TypeScript and collects component dependencies.
- */
-export function tsTypeOf(schema, dependencies, typeNames, options) {
-  return createTypeResolver({dependencies, typeNames, ...options}).typeOf(schema);
-}
-
-export function nullableTsTypeOf(schema, dependencies, typeNames, options) {
-  return createTypeResolver({dependencies, typeNames, ...options}).nullableTypeOf(schema);
-}

package/src/generators/models/utils.js

@@ -1,14 +1,3 @@
-import fs from 'node:fs/promises';
-
-/**
- * Supprime et recrée un dossier (idempotent)
- * @param {string} dir
- */
-export async function ensureCleanDir(dir) {
-  await fs.rm(dir, { recursive: true, force: true });
-  await fs.mkdir(dir, { recursive: true });
-}
-
 const RESERVED = new Set([
   'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do',
   'else', 'enum', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'import',

package/src/generators/models/write-model-files.js

@@ -1,30 +1,20 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { ensureCleanDir } from '../../infrastructure/files.js';
 import { renderTemplateToFile } from './handlebars.js';
 import { buildModelsFromOpenAPI } from './openapi-to-models.js';
-import { ensureCleanDir } from './utils.js';
 
 const currentDir = path.dirname(fileURLToPath(import.meta.url));
 const templatesDir = path.join(currentDir, 'templates');
 
-export async function writeModelFiles({ projectDir, spec, requiredMode, formats, include, exclude, debug, log }) {
+export async function writeModelFiles({ projectDir, spec, include, exclude, log }) {
   const outputDir = path.resolve(projectDir, 'src', 'models');
-  if (debug) {
-    log?.debug?.('[meridiane] generate models', {
-      outputDir,
-      requiredMode,
-      formats: Array.isArray(formats) ? formats : [],
-      includeCount: include.length,
-      excludeCount: exclude.length,
-    });
-  }
+  log.debug('[meridiane] generate models', { outputDir, includeCount: include.length, excludeCount: exclude.length });
 
   await ensureCleanDir(outputDir);
 
   const { models } = buildModelsFromOpenAPI(spec, {
-    requiredMode,
-    formats: Array.isArray(formats) ? formats : [],
     includeSchemaNames: include,
     excludeSchemaNames: exclude,
   });
@@ -37,7 +27,7 @@ export async function writeModelFiles({ projectDir, spec, requiredMode, formats,
         name: model.name,
         props: model.props,
         imports: model.imports,
-        extendsTypes: model.extendsTypes || [],
+        extendsTypes: model.extendsTypes,
         extendsItem: model.extendsItem === true,
         type: model.type,
         separator: model.imports.length > 0 ? '\n' : '',
@@ -51,5 +41,5 @@ export async function writeModelFiles({ projectDir, spec, requiredMode, formats,
     ctx: { models: models.map(({ name }) => ({ name })) },
   });
 
-  if (debug) log?.debug?.(`[meridiane] ${models.length} model(s) generated`);
+  log.debug(`[meridiane] ${models.length} model(s) generated`);
 }

package/src/infrastructure/dev-project.js

@@ -1,8 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
-const SANDBOX_PACKAGE_NAME = '@obsidiane/meridiane-sandbox';
-
 async function isFile(filePath) {
   try {
     return (await fs.stat(filePath)).isFile();
@@ -11,38 +9,7 @@ async function isFile(filePath) {
   }
 }
 
-async function readPackageName(projectRoot) {
-  try {
-    const packageJson = JSON.parse(await fs.readFile(path.join(projectRoot, 'package.json'), 'utf8'));
-    return typeof packageJson.name === 'string' ? packageJson.name : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-async function isSandboxProject(projectRoot) {
-  return (await readPackageName(projectRoot)) === SANDBOX_PACKAGE_NAME;
-}
-
 export async function resolveDevAppRoot(startDir) {
   if (await isFile(path.join(startDir, 'package.json'))) return startDir;
   throw new Error('No package.json found. Run `meridiane dev` from your Angular app root.');
 }
-
-export async function resolveSandboxAppRoot(startDir) {
-  if (await isSandboxProject(startDir)) return startDir;
-
-  const playgroundRoot = path.join(startDir, 'playground', 'angular-app');
-  if (await isSandboxProject(playgroundRoot)) return playgroundRoot;
-
-  throw new Error(
-    'Missing <packageName>. Run from the playground app (`playground/angular-app`) or provide a package name.'
-  );
-}
-
-export async function resolveSpecSource({useSandboxDefaults, appRoot, specArg}) {
-  if (!useSandboxDefaults || specArg) return specArg;
-
-  const localSpec = path.resolve(appRoot, '..', 'api-platform', 'var', 'openapi.json');
-  return (await isFile(localSpec)) ? localSpec : 'http://localhost:8000/api/docs.json';
-}

package/src/infrastructure/files.js

@@ -0,0 +1,15 @@
+import fs from 'node:fs/promises';
+
+export async function readJson(filePath) {
+  return JSON.parse(await fs.readFile(filePath, 'utf8'));
+}
+
+export async function writeJson(filePath, data) {
+  await fs.writeFile(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+
+/** Removes then recreates a directory. */
+export async function ensureCleanDir(dir) {
+  await fs.rm(dir, { recursive: true, force: true });
+  await fs.mkdir(dir, { recursive: true });
+}

package/src/infrastructure/local-package-install.js

@@ -38,7 +38,7 @@ export async function installPackageFromDist({packageName, distDir, appRoot, log
   const packageDir = scope ? path.join(nodeModules, scope, name) : path.join(nodeModules, name);
   const displayName = scope ? `${scope}/${name}` : name;
 
-  log?.step?.(`installation locale dans node_modules (${displayName})`);
+  log.step(`installation locale dans node_modules (${displayName})`);
 
   await fs.rm(packageDir, {recursive: true, force: true});
   await fs.mkdir(path.dirname(packageDir), {recursive: true});
@@ -71,7 +71,7 @@ async function invalidateAngularViteCache({appRoot, packageName, log}) {
   }
 
   if (removedFiles > 0) {
-    log?.info?.(`cache Angular/Vite invalidé (${removedFiles} fichier(s)) pour ${packageName}`);
+    log.info(`cache Angular/Vite invalidé (${removedFiles} fichier(s)) pour ${packageName}`);
   }
 }
 

package/src/infrastructure/logger.js

@@ -13,8 +13,6 @@ export function createLogger({ debug = false } = {}) {
   const prefix = color('35', 'meridiane');
 
   return {
-    debugEnabled: debug,
-
     title(text) {
       console.log(line('🌙', `${prefix} ${text}`));
     },

package/templates/angular-bridge/README.md

@@ -1,308 +1,56 @@
 # __PACKAGE_NAME__
 
-Bridge Angular (runtime + models TypeScript) pour une API Platform (Hydra/JSON-LD), avec support Mercure/SSE optionnel.
+Bridge Angular de l'API, généré par [Meridiane 3](https://github.com/obsidiane-lab/meridiane/blob/master/docs/README.md) depuis son contrat OpenAPI. Ne pas modifier : régénérer quand le contrat change.
 
-Le package expose une API Angular volontairement minimaliste :
-- `provideBridge()` pour configurer le bridge (HTTP + tokens + Mercure) ;
-- `FacadeFactory` / `ResourceFacade<T>` pour une API orientée ressource ;
-- `BridgeFacade` pour des appels ad-hoc.
+Il fournit les modèles TypeScript, le client HTTP (JSON-LD, Hydra, merge-patch) et le temps réel Mercure 1.0. Angular 20, 21 ou 22 ; RxJS 7.8.
 
-## Installation
-
-```bash
-npm i __PACKAGE_NAME__
-```
-
-Le bridge est conçu pour être installé dans une application Angular. Les dépendances Angular et RxJS sont des `peerDependencies`.
-
-## Compatibilité
-
-- Angular `@angular/*` `^20.0.0 || ^21.0.0`
-- RxJS `^7.8.0`
-
-## Démarrage rapide
-
-Configurez le bridge au démarrage de l’application avec `provideBridge()` (requis).
-
-### Application standalone (recommandé)
+## Configurer
 
 ```ts
-// app.config.ts (ou main.ts)
-import {ApplicationConfig} from '@angular/core';
 import {provideBridge} from '__PACKAGE_NAME__';
 
 export const appConfig: ApplicationConfig = {
   providers: [
     provideBridge({
-      baseUrl: 'https://api.example.com',
-      mercure: {hubUrl: 'https://api.example.com/.well-known/mercure'},
+      baseUrl: '/',                                        // API sur la même origine que le front
+      mercure: {
+        hubUrl: '/.well-known/mercure',
+        authorize: '/api/mercure/authorization',           // pose et renouvelle le cookie Mercure
+      },
     }),
   ],
 };
 ```
 
-### Application NgModule
-
-```ts
-import {NgModule} from '@angular/core';
-import {provideBridge} from '__PACKAGE_NAME__';
-
-@NgModule({
-  providers: [
-    provideBridge({baseUrl: 'https://api.example.com'}),
-  ],
-})
-export class AppModule {}
-```
-
-## Configuration
-
-`provideBridge({ ... })` accepte notamment :
-- `baseUrl` (requis) ;
-- `auth` (Bearer ou interceptor custom) ;
-- `http` (`withCredentials` HTTP par défaut) ;
-- `mercure` (hubUrl + `topicMode` + stratégie de connexions SSE `connectionMode`/`maxUrlLength`) ;
-- `defaults` (headers/timeout/retries) ;
-- `singleFlight` (déduplication “in-flight” des requêtes HTTP identiques `GET/HEAD/OPTIONS`) ;
-- `debug` (logs runtime) ;
-- `extraInterceptors` (interceptors Angular additionnels).
-
-Les comportements HTTP internes du bridge s'appliquent uniquement aux requêtes
-appartenant à l'origine et au chemin de `baseUrl`. Les interceptors personnalisés
-restent responsables de leur propre périmètre.
-
-### Cookies / `withCredentials`
-
-Le bridge peut envoyer des cookies (sessions) côté HTTP et SSE.
-
-Vous pouvez configurer explicitement le HTTP via `http.withCredentials` :
-- `true` → cookies envoyés sur les requêtes HTTP
-- `false` → cookies désactivés côté HTTP
-
-`mercure.init.credentials` pilote uniquement Mercure/SSE :
-- `credentials: 'include'` (défaut) → cookies envoyés sur EventSource
-- `credentials: 'omit'` → cookies désactivés côté SSE
-
-Compat legacy :
-- si `http.withCredentials` est absent, le bridge conserve le comportement historique et le déduit de `mercure.init.credentials`
-
-Vous pouvez aussi surcharger appel par appel via `opts.withCredentials` sur les appels HTTP.
-
-```ts
-import {provideBridge} from '__PACKAGE_NAME__';
-
-provideBridge({
-  baseUrl: 'https://api.example.com',
-  http: {withCredentials: true},
-  mercure: {
-    hubUrl: 'https://api.example.com/.well-known/mercure',
-    init: {credentials: 'omit'},
-  },
-});
-```
-
-### Auth (Bearer)
-
-`auth` accepte :
-- une string (token Bearer),
-- `{ type: 'bearer', token }`,
-- `{ type: 'bearer', getToken }` (sync ou async),
-- ou un `HttpInterceptorFn` custom.
-
-Le Bearer intégré est ajouté uniquement aux requêtes dont l’origine et le chemin
-appartiennent au `baseUrl` configuré. Une requête vers un autre service conserve
-donc ses en-têtes d’origine. Un interceptor custom garde le comportement Angular
-standard et reste responsable de son propre périmètre.
-
-```ts
-import {provideBridge} from '__PACKAGE_NAME__';
-
-provideBridge({
-  baseUrl: 'https://api.example.com',
-  auth: {type: 'bearer', getToken: () => localStorage.getItem('token') ?? undefined},
-});
-```
-
-### Defaults (headers / timeout / retries)
-
-```ts
-import {provideBridge} from '__PACKAGE_NAME__';
-
-provideBridge({
-  baseUrl: 'https://api.example.com',
-  defaults: {
-    headers: {'X-Requested-With': 'fetch'},
-    timeoutMs: 15_000,
-    retries: {count: 2, delayMs: 250, methods: ['GET']},
-  },
-});
-```
-
-### Debug
-
-```ts
-import {provideBridge} from '__PACKAGE_NAME__';
-
-provideBridge({baseUrl: 'https://api.example.com', debug: true});
-```
-
-## Appeler l’API
-
-### Style orienté ressource (`FacadeFactory` + `ResourceFacade<T>`)
-
-```ts
-import {inject} from '@angular/core';
-import {FacadeFactory, ResourceFacade, Item} from '__PACKAGE_NAME__';
-
-type Book = Item & {title?: string};
-
-export class BooksService {
-  private readonly factory = inject(FacadeFactory);
-  readonly books: ResourceFacade<Book> = this.factory.create<Book>({url: '/api/books'});
-}
-```
-
-Exemples :
-
-```ts
-// collection Hydra
-this.books.getCollection$({page: 1, itemsPerPage: 20, filters: {title: 'Dune'}});
-
-// item (souvent via @id)
-this.books.get$(book['@id']!);
-
-// write
-this.books.post$({title: 'Neuromancer'});
-this.books.patch$(book['@id']!, {title: 'Count Zero'});
-this.books.delete$(book['@id']!);
-```
-
-### Style ad-hoc (`BridgeFacade`)
-
-```ts
-import {inject} from '@angular/core';
-import {BridgeFacade} from '__PACKAGE_NAME__';
-
-export class HealthService {
-  private readonly bridge = inject(BridgeFacade);
-  getHealth$() {
-    return this.bridge.get$<{status: string}>('/health');
-  }
-}
-```
-
-## Realtime (Mercure/SSE)
-
-Le realtime est inactif tant que `mercure.hubUrl` n’est pas fourni à `provideBridge()`.
-
-```ts
-provideBridge({
-  baseUrl: 'https://api.example.com',
-  mercure: {hubUrl: 'https://api.example.com/.well-known/mercure', topicMode: 'url'},
-});
-```
-
-### Concurrence
+`provideBridge()` installe `HttpClient`. Options, cookies et topologies : [Configuration](https://github.com/obsidiane-lab/meridiane/blob/master/docs/configuration.md).
 
-Le bridge propose 2 stratégies SSE configurables via `provideBridge({mercure: ...})` :
-- `connectionMode: 'single'` : chaque appel `watch*` ouvre sa propre connexion SSE ;
-- `connectionMode: 'auto'` (défaut) : les topics sont mutualisés, puis découpés automatiquement en plusieurs connexions si l’URL Mercure dépasse `maxUrlLength` (défaut `1900`).
-
-Vous pouvez forcer une connexion dédiée par appel avec `newConnection: true` sur `watch$`, `watchSubResource$` et `watchTypes$`.
+## Utiliser une ressource
 
 ```ts
-provideBridge({
-  baseUrl: 'https://api.example.com',
-  mercure: {
-    hubUrl: 'https://api.example.com/.well-known/mercure',
-    connectionMode: 'auto',
-    maxUrlLength: 1900,
-  },
-});
-```
-
-Côté HTTP, le bridge déduplique les requêtes identiques tant qu’elles sont en cours (single-flight, activé par défaut) :
-- `GET` / `HEAD` / `OPTIONS` : deux appels identiques partagent le même appel réseau et reçoivent la même réponse ;
-- les méthodes avec body (`POST`/`PUT`/`PATCH`/`DELETE`) ne sont pas dédupliquées.
-
-Ce n’est pas un cache : une fois la requête terminée, un nouvel appel identique relance un nouvel appel réseau.
-
-Pour désactiver :
-
-```ts
-provideBridge({baseUrl: 'https://api.example.com', singleFlight: false});
-```
-
-API :
-- `ResourceFacade<T>.watch$(iri | iri[], {newConnection?})` / `unwatch(iri | iri[])`
-- `ResourceFacade<T>.watchSubResource$(iri | iri[], 'field.path', {newConnection?})`
-- `BridgeFacade.watch$(iri | iri[], filter?, {newConnection?})` / `unwatch(iri | iri[])`
-- `BridgeFacade.watchTypes$(iri | iri[], resourceTypes, cfg?, {newConnection?})` (topics “multi-entités”, filtrage par type)
-- `BridgeFacade.realtimeDiagnostics$()` (état courant des connexions SSE actives)
-
-Note SSR : la connexion SSE ne s’ouvre que dans le navigateur.
+import {FacadeFactory, isResourceDeletion, type Project} from '__PACKAGE_NAME__';
 
-### Topic “multi-entités” (event-bus)
+const projects = inject(FacadeFactory).create<Project>({url: '/api/projects'});
 
-Quand un même topic Mercure publie plusieurs types de payloads (sans lien entre eux),
-utilisez `BridgeFacade.watchTypes$()`.
-Le flux renvoie une union discriminée par `resourceType` (par défaut via `@type` en JSON-LD).
+projects.getCollection$({page: 1, itemsPerPage: 20});   // Collection<Project>
+projects.get$('/api/projects/42');                       // Project
+projects.post$({name: 'Refonte'});
+projects.patch$('/api/projects/42', {archived: true});
+projects.delete$('/api/projects/42');
 
-Fonctionnement (résumé) :
-- le bridge s’abonne au(x) topic(s) Mercure (connexion dédiée ou mutualisée selon `connectionMode`)
-- chaque event JSON recu est testé sur le champ de discrimination (`@type` par défaut)
-- seuls les `resourceType` explicitement demandés sont émis
-- chaque event émis est `{ resourceType, payload }`
-
-Important (provenance des events) :
-- `watchTypes$` filtre par type (`payload[discriminator]`), pas par provenance réseau du topic.
-- En mode mutualisé (`connectionMode: 'auto'` et sans `newConnection`), un event d’un autre topic partagé peut être émis s’il porte un type autorisé.
-- Si vous voulez ecouter strictement un seul topic, utilisez une connexion dédiée :
-  `watchTypes$(..., {newConnection: true})` (ou `connectionMode: 'single'` globalement).
-
-Configuration :
-- `discriminator` : champ type (défaut `@type`)
-- `resourceTypes` : liste de strings à accepter (`['Conversation', 'Message']`, etc.)
-
-```ts
-import {inject} from '@angular/core';
-import {BridgeFacade} from '__PACKAGE_NAME__';
-import type {Item} from '__PACKAGE_NAME__';
-
-type Conversation = Item & {title?: string | null};
-type Message = Item & {originalText?: string | null};
-
-type Registry = {
-  Conversation: Conversation;
-  Message: Message;
-};
-
-const bridge = inject(BridgeFacade);
-
-bridge.watchTypes$<Registry>(
-  '/api/events/me',
-  ['Conversation', 'Message'],
-  {discriminator: '@type'},
-  {newConnection: true} // isolation stricte du topic
-).subscribe((evt) => {
-  switch (evt.resourceType) {
-    case 'Conversation':
-      // evt.payload: Conversation
-      break;
-    case 'Message':
-      // evt.payload: Message
-      break;
-  }
+projects.watch$().subscribe((resource) => {             // toute la ressource, en direct
+  if (isResourceDeletion(resource)) store.remove(resource['@id']);
+  else store.upsert(resource);
 });
 ```
 
-## Models TypeScript
+Pour un endpoint hors ressource ou un topic Mercure personnalisé : `BridgeFacade`.
 
-Les models générés (si présents) sont exportés au même niveau que le runtime :
-
-```ts
-import type {Item} from '__PACKAGE_NAME__';
-// import type {Book} from '__PACKAGE_NAME__';
-```
+## Documentation
 
-En JSON-LD (`application/ld+json`), l’IRI est typiquement dans `model['@id']`.
+[Démarrage](https://github.com/obsidiane-lab/meridiane/blob/master/docs/demarrage.md) ·
+[HTTP](https://github.com/obsidiane-lab/meridiane/blob/master/docs/http.md) ·
+[Temps réel](https://github.com/obsidiane-lab/meridiane/blob/master/docs/temps-reel.md) ·
+[Backend](https://github.com/obsidiane-lab/meridiane/blob/master/docs/backend.md) ·
+[Recettes](https://github.com/obsidiane-lab/meridiane/blob/master/docs/recettes.md) ·
+[Référence](https://github.com/obsidiane-lab/meridiane/blob/master/docs/reference.md) ·
+[Dépannage](https://github.com/obsidiane-lab/meridiane/blob/master/docs/depannage.md)

package/templates/angular-bridge/package.json

@@ -2,8 +2,8 @@
   "name": "__LIB_NAME__",
   "version": "0.0.1",
   "peerDependencies": {
-    "@angular/common": "^20.0.0 || ^21.0.0",
-    "@angular/core": "^20.0.0 || ^21.0.0",
+    "@angular/common": "^20.0.0 || ^21.0.0 || ^22.0.0",
+    "@angular/core": "^20.0.0 || ^21.0.0 || ^22.0.0",
     "rxjs": "^7.8.0"
   },
   "dependencies": {

package/templates/angular-bridge/src/lib/bridge/rest/http-request.options.ts

@@ -8,23 +8,14 @@ export function resolveHttpCallOptions(options: HttpCallOptions | undefined, wit
   };
 }
 
-export function buildHttpRequestOptions(
-  req: HttpRequestConfig,
-  {withCredentialsDefault}: {withCredentialsDefault: boolean}
-): Record<string, unknown> {
-  const {query, body, headers, responseType, withCredentials, options = {}} = req;
-  const mergedOptions: Record<string, unknown> = {...options};
-
-  if (headers) mergedOptions['headers'] = headers;
-  if (query) mergedOptions['params'] = toHttpParams(query);
-  if (body !== undefined) mergedOptions['body'] = body;
-
-  const inheritedResponseType = mergedOptions['responseType'];
-  const inheritedWithCredentials = mergedOptions['withCredentials'];
-
-  mergedOptions['responseType'] = responseType ?? inheritedResponseType ?? 'json';
-  mergedOptions['withCredentials'] = withCredentials ?? inheritedWithCredentials ?? withCredentialsDefault;
-  mergedOptions['observe'] = 'body';
-
-  return mergedOptions;
+export function buildHttpRequestOptions(request: HttpRequestConfig, withCredentialsDefault: boolean) {
+  return {
+    headers: request.headers,
+    params: request.query ? toHttpParams(request.query) : undefined,
+    body: request.body,
+    // The caller types the response with `R`; `HttpClient.request` only infers it for `json`.
+    responseType: (request.responseType ?? 'json') as 'json',
+    withCredentials: request.withCredentials ?? withCredentialsDefault,
+    observe: 'body' as const,
+  };
 }