@obsidiane/meridiane 2.0.7 → 2.0.11

package/{tools/infra → src/infrastructure}/standalone-workspace.js

@@ -5,13 +5,13 @@ import { createRequire } from 'node:module';
 import { runCommand } from './exec.js';
 import { writeJsonIfChanged } from './json.js';
 
-async function ensureDir(p) {
-  await fs.mkdir(p, { recursive: true });
+async function ensureDirectory(directory) {
+  await fs.mkdir(directory, { recursive: true });
 }
 
-async function exists(p) {
+async function exists(filePath) {
   try {
-    await fs.stat(p);
+    await fs.stat(filePath);
     return true;
   } catch {
     return false;
@@ -19,16 +19,15 @@ async function exists(p) {
 }
 
 function toolchainPackageJson({ angularVersion, ngPackagrVersion, typescriptVersion, rxjsVersion, tslibVersion }) {
-  const v = angularVersion;
   return {
     name: 'meridiane-standalone-workspace',
     private: true,
     description: 'Temporary workspace created by @obsidiane/meridiane (standalone build).',
     devDependencies: {
-      '@angular/common': v,
-      '@angular/compiler': v,
-      '@angular/compiler-cli': v,
-      '@angular/core': v,
+      '@angular/common': angularVersion,
+      '@angular/compiler': angularVersion,
+      '@angular/compiler-cli': angularVersion,
+      '@angular/core': angularVersion,
       'ng-packagr': ngPackagrVersion,
       rxjs: rxjsVersion,
       tslib: tslibVersion,
@@ -62,8 +61,8 @@ export async function ensureStandaloneWorkspace({ repoRoot, log }) {
   const distRoot = path.join(repoRoot, 'dist');
   const workspaceRoot = path.join(distRoot, '.meridiane-workspace');
 
-  await ensureDir(distRoot);
-  await ensureDir(workspaceRoot);
+  await ensureDirectory(distRoot);
+  await ensureDirectory(workspaceRoot);
 
   const detected = await detectToolchainVersions(repoRoot);
   const angularVersion = detected.angularVersion ?? '21.1.4';
@@ -80,7 +79,7 @@ export async function ensureStandaloneWorkspace({ repoRoot, log }) {
   await writeJsonIfChanged(path.join(workspaceRoot, 'tsconfig.json'), rootTsconfigJson());
 
   const npmCacheDir = path.join(workspaceRoot, '.npm-cache');
-  await ensureDir(npmCacheDir);
+  await ensureDirectory(npmCacheDir);
 
   const requireFromWs = createRequire(path.join(workspaceRoot, 'package.json'));
 
@@ -88,26 +87,29 @@ export async function ensureStandaloneWorkspace({ repoRoot, log }) {
 }
 
 async function detectToolchainVersions(repoRoot) {
-  const pkgPath = path.join(repoRoot, 'package.json');
+  const packageJsonPath = path.join(repoRoot, 'package.json');
   try {
-    const raw = await fs.readFile(pkgPath, 'utf8');
-    const parsed = JSON.parse(raw);
-    const angularVersion = readDependencyVersion(parsed, '@angular/core');
-    const ngPackagrVersion = readDependencyVersion(parsed, 'ng-packagr');
-    const typescriptVersion = readDependencyVersion(parsed, 'typescript');
-    const rxjsVersion = readDependencyVersion(parsed, 'rxjs');
-    const tslibVersion = readDependencyVersion(parsed, 'tslib');
+    const content = await fs.readFile(packageJsonPath, 'utf8');
+    const packageJson = JSON.parse(content);
+    const angularVersion = readDependencyVersion(packageJson, '@angular/core');
+    const ngPackagrVersion = readDependencyVersion(packageJson, 'ng-packagr');
+    const typescriptVersion = readDependencyVersion(packageJson, 'typescript');
+    const rxjsVersion = readDependencyVersion(packageJson, 'rxjs');
+    const tslibVersion = readDependencyVersion(packageJson, 'tslib');
     return { angularVersion, ngPackagrVersion, typescriptVersion, rxjsVersion, tslibVersion };
   } catch {
     return {};
   }
 }
 
-function readDependencyVersion(pkg, depName) {
-  const deps = pkg?.dependencies || {};
-  const devDeps = pkg?.devDependencies || {};
-  const peerDeps = pkg?.peerDependencies || {};
-  const value = deps[depName] ?? devDeps[depName] ?? peerDeps[depName];
+function readDependencyVersion(packageJson, dependencyName) {
+  const dependencies = packageJson?.dependencies || {};
+  const devDependencies = packageJson?.devDependencies || {};
+  const peerDependencies = packageJson?.peerDependencies || {};
+  const value =
+    dependencies[dependencyName] ??
+    devDependencies[dependencyName] ??
+    peerDependencies[dependencyName];
   return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
 }
 
@@ -127,9 +129,9 @@ function deriveToolchainDefaultsFromAngular(angularVersion) {
 
 export async function ensureToolchainInstalled({ workspaceRoot, requireFromWs, npmCacheDir, log }) {
   // Prefer using existing (hoisted) deps during local dev; in CI this will trigger installation.
-  const canResolve = (id) => {
+  const canResolve = (packageId) => {
     try {
-      requireFromWs.resolve(id);
+      requireFromWs.resolve(packageId);
       return true;
     } catch {
       return false;
@@ -150,9 +152,9 @@ export async function ensureToolchainInstalled({ workspaceRoot, requireFromWs, n
   };
 
   // We avoid generating a lockfile in the backend repo by keeping everything under dist/.
-  const npmCmd = 'npm';
+  const npmCommand = 'npm';
   const args = ['install', '--silent', '--no-progress'];
-  const code = await runCommand(npmCmd, args, { cwd: workspaceRoot, env });
+  const code = await runCommand(npmCommand, args, { cwd: workspaceRoot, env });
 
   if (code !== 0) throw new Error(`Toolchain install failed (npm exit ${code})`);
   if (!(await exists(path.join(workspaceRoot, 'node_modules')))) {

package/templates/{_lib_template → angular-bridge}/README.md

@@ -60,27 +60,40 @@ export class AppModule {}
 `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.
 
-Le comportement `withCredentials` par défaut est déduit de `mercure.init` :
-- `credentials: 'include'` (défaut) → cookies envoyés
-- `credentials: 'omit'` → cookies non envoyés
+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
 
-Vous pouvez aussi surcharger au cas par cas via `opts.withCredentials` sur les appels HTTP.
+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'},
@@ -96,6 +109,11 @@ provideBridge({
 - `{ 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__';
 

package/templates/angular-bridge/src/lib/bridge/rest/api-platform.adapter.ts

@@ -0,0 +1,82 @@
+import {HttpClient} from '@angular/common/http';
+import {Observable} from 'rxjs';
+import {toHttpParams} from './query-builder';
+import {buildHttpRequestOptions, resolveHttpCallOptions} from './http-request.options';
+import {
+  Collection,
+  HttpCallOptions,
+  HttpRequestConfig,
+  Iri,
+  IriRequired,
+  Item,
+  AnyQuery,
+  ResourceRepository,
+} from '../../ports/resource-repository.port';
+import {resolveUrl} from '../../utils/url';
+
+export class ApiPlatformRestRepository<T extends Item> implements ResourceRepository<T> {
+  constructor(
+    private readonly http: HttpClient,
+    private readonly apiBase: string,
+    private readonly resourcePath: Iri,
+    private readonly httpWithCredentialsDefault: boolean,
+  ) {
+  }
+
+  getCollection$(query?: AnyQuery, options?: HttpCallOptions): Observable<Collection<T>> {
+    return this.http.get<Collection<T>>(this.resolveUrl(this.resourcePath), {
+      ...resolveHttpCallOptions(options, this.httpWithCredentialsDefault),
+      params: toHttpParams(query),
+    });
+  }
+
+  get$(iri: IriRequired, options?: HttpCallOptions): Observable<T> {
+    return this.http.get<T>(this.resolveUrl(iri), resolveHttpCallOptions(options, this.httpWithCredentialsDefault));
+  }
+
+  post$(payload: Partial<T>, options?: HttpCallOptions): Observable<T> {
+    return this.http.post<T>(
+      this.resolveUrl(this.resourcePath),
+      payload,
+      resolveHttpCallOptions(options, this.httpWithCredentialsDefault)
+    );
+  }
+
+  patch$(iri: IriRequired, changes: Partial<T>, options?: HttpCallOptions): Observable<T> {
+    return this.http.patch<T>(
+      this.resolveUrl(iri),
+      changes,
+      resolveHttpCallOptions(options, this.httpWithCredentialsDefault)
+    );
+  }
+
+  put$(iri: IriRequired, payload: Partial<T>, options?: HttpCallOptions): Observable<T> {
+    return this.http.put<T>(
+      this.resolveUrl(iri),
+      payload,
+      resolveHttpCallOptions(options, this.httpWithCredentialsDefault)
+    );
+  }
+
+  delete$(iri: IriRequired, options?: HttpCallOptions): Observable<void> {
+    return this.http.delete<void>(
+      this.resolveUrl(iri),
+      resolveHttpCallOptions(options, this.httpWithCredentialsDefault)
+    );
+  }
+
+  request$<R = unknown, B = unknown>(request: HttpRequestConfig<B>): Observable<R> {
+    // Low-level escape hatch for non-standard endpoints (custom controllers, uploads, etc.).
+    const {method, url} = request;
+
+    const targetUrl = this.resolveUrl(url ?? this.resourcePath);
+    const mergedOptions = buildHttpRequestOptions(request, {withCredentialsDefault: this.httpWithCredentialsDefault});
+    return this.http.request<R>(method, targetUrl, mergedOptions as {observe: 'body'});
+  }
+
+  private resolveUrl(path?: Iri): string {
+    const effectivePath = path ?? this.resourcePath;
+    if (!effectivePath) throw new Error('ApiPlatformRestRepository: missing url and resourcePath');
+    return resolveUrl(this.apiBase, effectivePath);
+  }
+}

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

@@ -0,0 +1,30 @@
+import {HttpCallOptions, HttpRequestConfig} from '../../ports/resource-repository.port';
+import {toHttpParams} from './query-builder';
+
+export function resolveHttpCallOptions(options: HttpCallOptions | undefined, withCredentialsDefault: boolean) {
+  return {
+    headers: options?.headers,
+    withCredentials: options?.withCredentials ?? withCredentialsDefault,
+  };
+}
+
+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;
+}

package/templates/{_lib_template → angular-bridge}/src/lib/bridge/rest/query-builder.ts

@@ -1,14 +1,14 @@
 import {HttpParams} from '@angular/common/http';
 import {AnyQuery, Query, QueryParamValue} from '../../ports/resource-repository.port';
 
-export function toHttpParams(q: AnyQuery | undefined): HttpParams {
-  if (!q) return new HttpParams();
-  if (q instanceof HttpParams) return q;
+export function toHttpParams(query: AnyQuery | undefined): HttpParams {
+  if (!query) return new HttpParams();
+  if (query instanceof HttpParams) return query;
 
   const fromObject: Record<string, string | string[]> = {};
 
   const consumed = new Set<string>();
-  const maybeQuery = q as Query;
+  const maybeQuery = query as Query;
   if (maybeQuery.page != null) {
     fromObject['page'] = String(maybeQuery.page);
     consumed.add('page');
@@ -18,16 +18,16 @@ export function toHttpParams(q: AnyQuery | undefined): HttpParams {
     consumed.add('itemsPerPage');
   }
 
-  if (q.filters) {
+  if (query.filters) {
     consumed.add('filters');
-    for (const [k, v] of Object.entries(q.filters)) {
-      assign(fromObject, k, v);
+    for (const [key, value] of Object.entries(query.filters)) {
+      assign(fromObject, key, value);
     }
   }
 
-  for (const [k, v] of Object.entries(q as Record<string, QueryParamValue>)) {
-    if (consumed.has(k)) continue;
-    assign(fromObject, k, v);
+  for (const [key, value] of Object.entries(query as Record<string, QueryParamValue>)) {
+    if (consumed.has(key)) continue;
+    assign(fromObject, key, value);
   }
 
   return new HttpParams({fromObject});

package/templates/angular-bridge/src/lib/bridge/sse/mercure-connections.ts

@@ -0,0 +1,255 @@
+import {BehaviorSubject, Observable, Subject} from 'rxjs';
+import {takeUntil} from 'rxjs/operators';
+import {
+  BridgeLogger,
+  MercureConnectionMode,
+  RealtimeDiagnostics,
+} from '../../bridge.types';
+import {RealtimeStatus} from '../../ports/realtime.port';
+import {EventSourceWrapper} from './eventsource-wrapper';
+import {MercureUrlBuilder} from './mercure-url.builder';
+
+export type IncomingMessage = {type: string; data: string; lastEventId?: string};
+
+type ConnectionScope = 'shared' | 'dedicated';
+
+type ManagedConnection = {
+  id: string;
+  key: string;
+  scope: ConnectionScope;
+  groupId?: string;
+  topics: ReadonlySet<string>;
+  urlLength: number;
+  wrapper: EventSourceWrapper;
+  stop$: Subject<void>;
+  status: RealtimeStatus;
+};
+
+type ConnectionTarget = Subject<IncomingMessage>;
+
+type ConnectionManagerOptions = {
+  hubUrl?: string;
+  withCredentials: boolean;
+  mode: MercureConnectionMode;
+  maxUrlLength: number;
+  logger?: BridgeLogger;
+  destroy$: Observable<void>;
+  nextId: (prefix: string) => string;
+};
+
+export class MercureConnectionManager {
+  private readonly urlBuilder = new MercureUrlBuilder();
+  private readonly connections = new Map<string, ManagedConnection>();
+  private readonly sharedConnections = new Map<string, ManagedConnection>();
+  private readonly dedicatedGroups = new Map<string, Set<string>>();
+  private readonly lastEventIdByKey = new Map<string, string>();
+
+  private readonly statusSubject = new BehaviorSubject<RealtimeStatus>('closed');
+  private readonly diagnosticsSubject: BehaviorSubject<RealtimeDiagnostics>;
+
+  readonly status$ = this.statusSubject.asObservable();
+  readonly diagnostics$: Observable<RealtimeDiagnostics>;
+
+  constructor(private readonly options: ConnectionManagerOptions) {
+    this.diagnosticsSubject = new BehaviorSubject<RealtimeDiagnostics>(this.createDiagnostics());
+    this.diagnostics$ = this.diagnosticsSubject.asObservable();
+  }
+
+  reconcileShared(topics: Iterable<string>, target: ConnectionTarget): void {
+    if (!this.options.hubUrl) {
+      this.closeShared();
+      return;
+    }
+
+    const desiredConnections = new Map<string, ReadonlySet<string>>();
+    for (const partition of this.partitionTopics(topics)) {
+      const partitionTopics = new Set(partition);
+      desiredConnections.set(this.connectionKey(partitionTopics, 'shared'), partitionTopics);
+    }
+
+    for (const [key, connection] of [...this.sharedConnections.entries()]) {
+      if (!desiredConnections.has(key)) this.close(connection.id);
+    }
+
+    for (const [key, partitionTopics] of desiredConnections) {
+      if (this.sharedConnections.has(key)) continue;
+      const connection = this.open({key, scope: 'shared', topics: partitionTopics, target});
+      this.sharedConnections.set(key, connection);
+    }
+  }
+
+  openDedicated(groupId: string, topics: Iterable<string>, target: ConnectionTarget): void {
+    this.dedicatedGroups.set(groupId, new Set());
+
+    for (const partition of this.partitionTopics(topics)) {
+      const partitionTopics = new Set(partition);
+      const key = this.connectionKey(partitionTopics, 'dedicated', groupId);
+      const connection = this.open({key, scope: 'dedicated', groupId, topics: partitionTopics, target});
+      this.dedicatedGroups.get(groupId)?.add(connection.id);
+    }
+  }
+
+  closeShared(): void {
+    for (const connection of [...this.sharedConnections.values()]) this.close(connection.id);
+  }
+
+  closeDedicated(groupId: string): void {
+    const connectionIds = this.dedicatedGroups.get(groupId);
+    if (!connectionIds) return;
+
+    for (const connectionId of [...connectionIds]) this.close(connectionId);
+    this.dedicatedGroups.delete(groupId);
+  }
+
+  closeAll(): void {
+    for (const connection of [...this.connections.values()]) this.close(connection.id);
+    this.sharedConnections.clear();
+    this.dedicatedGroups.clear();
+    this.updateStatus();
+  }
+
+  complete(): void {
+    this.statusSubject.complete();
+    this.diagnosticsSubject.complete();
+  }
+
+  private partitionTopics(topics: Iterable<string>): string[][] {
+    if (!this.options.hubUrl) return [];
+    return this.urlBuilder.partitionTopics(
+      this.options.hubUrl,
+      topics,
+      this.options.maxUrlLength,
+      this.options.mode === 'auto'
+    );
+  }
+
+  private open(params: {
+    key: string;
+    scope: ConnectionScope;
+    topics: ReadonlySet<string>;
+    target: ConnectionTarget;
+    groupId?: string;
+  }): ManagedConnection {
+    const {hubUrl, withCredentials, logger, destroy$, nextId} = this.options;
+    if (!hubUrl) throw new Error('Mercure hub URL is required to open a realtime connection.');
+
+    const lastEventId = this.lastEventIdByKey.get(params.key);
+    const url = this.urlBuilder.build(hubUrl, params.topics, lastEventId);
+
+    logger?.debug?.('[Mercure] connect', {
+      mode: this.options.mode,
+      scope: params.scope,
+      key: params.key,
+      urlLength: url.length,
+      topics: [...params.topics],
+      lastEventId,
+    });
+
+    const wrapper = new EventSourceWrapper(url, {withCredentials}, logger);
+    const stop$ = new Subject<void>();
+    const connection: ManagedConnection = {
+      id: nextId('conn'),
+      key: params.key,
+      scope: params.scope,
+      groupId: params.groupId,
+      topics: params.topics,
+      urlLength: url.length,
+      wrapper,
+      stop$,
+      status: 'connecting',
+    };
+
+    this.connections.set(connection.id, connection);
+
+    wrapper.status$
+      .pipe(takeUntil(stop$), takeUntil(destroy$))
+      .subscribe((status) => {
+        connection.status = status;
+        this.updateStatus();
+      });
+
+    wrapper.events$
+      .pipe(takeUntil(stop$), takeUntil(destroy$))
+      .subscribe((event) => {
+        if (event.lastEventId) this.lastEventIdByKey.set(params.key, event.lastEventId);
+        params.target.next({type: event.type, data: event.data, lastEventId: event.lastEventId});
+      });
+
+    try {
+      wrapper.open();
+      this.updateStatus();
+      return connection;
+    } catch (error) {
+      this.close(connection.id);
+      throw error;
+    }
+  }
+
+  private close(connectionId: string): void {
+    const connection = this.connections.get(connectionId);
+    if (!connection) return;
+
+    connection.status = 'closed';
+    connection.wrapper.close();
+    connection.stop$.next();
+    connection.stop$.complete();
+    this.connections.delete(connectionId);
+
+    if (connection.scope === 'shared') this.sharedConnections.delete(connection.key);
+    if (connection.scope === 'dedicated' && connection.groupId) {
+      const group = this.dedicatedGroups.get(connection.groupId);
+      group?.delete(connection.id);
+      if (group?.size === 0) this.dedicatedGroups.delete(connection.groupId);
+      this.lastEventIdByKey.delete(connection.key);
+    }
+
+    this.updateStatus();
+  }
+
+  private connectionKey(topics: ReadonlySet<string>, scope: ConnectionScope, groupId = ''): string {
+    const {hubUrl = '', withCredentials, mode} = this.options;
+    return [
+      scope,
+      groupId,
+      hubUrl,
+      withCredentials ? '1' : '0',
+      mode,
+      [...topics].sort().join('|'),
+    ].join('::');
+  }
+
+  private updateStatus(): void {
+    const statuses = [...this.connections.values()].map((connection) => connection.status);
+    this.statusSubject.next(aggregateStatus(statuses));
+    this.diagnosticsSubject.next(this.createDiagnostics());
+  }
+
+  private createDiagnostics(): RealtimeDiagnostics {
+    const connections = [...this.connections.values()]
+      .map((connection) => ({
+        id: connection.id,
+        scope: connection.scope,
+        status: connection.status,
+        topicCount: connection.topics.size,
+        topics: [...connection.topics].sort(),
+        urlLength: connection.urlLength,
+      }))
+      .sort((left, right) => left.scope.localeCompare(right.scope) || left.id.localeCompare(right.id));
+    const sharedConnections = connections.filter((connection) => connection.scope === 'shared').length;
+
+    return {
+      mode: this.options.mode,
+      maxUrlLength: this.options.maxUrlLength,
+      totalConnections: connections.length,
+      sharedConnections,
+      dedicatedConnections: connections.length - sharedConnections,
+      connections,
+    };
+  }
+}
+
+function aggregateStatus(statuses: RealtimeStatus[]): RealtimeStatus {
+  if (statuses.includes('connected')) return 'connected';
+  if (statuses.includes('connecting')) return 'connecting';
+  return 'closed';
+}

package/templates/angular-bridge/src/lib/bridge/sse/mercure-payload.ts

@@ -0,0 +1,82 @@
+import {BridgeLogger} from '../../bridge.types';
+import {SubscribeFilter} from '../../ports/realtime.port';
+import {Item} from '../../ports/resource-repository.port';
+import {MercureTopicMapper} from './mercure-topic.mapper';
+
+export function parseMercurePayload(raw: string, logger?: BridgeLogger): Item | undefined {
+  try {
+    const value: unknown = JSON.parse(raw);
+    return isRecord(value) ? value as Item : undefined;
+  } catch {
+    logger?.debug?.('[Mercure] invalid JSON payload ignored', {raw});
+    return undefined;
+  }
+}
+
+export function createPayloadTopicMatcher(
+  iris: string[],
+  filter: SubscribeFilter | undefined,
+  topicMapper: MercureTopicMapper
+): (payload: Item) => string | undefined {
+  const subscribedTopics = iris.map((iri) => normalizeIri(topicMapper.toPayloadIri(iri)));
+  const fieldPaths = [
+    ...(filter?.fields?.filter((field): field is string => typeof field === 'string' && field.length > 0) ?? []),
+    ...(typeof filter?.field === 'string' && filter.field.length > 0 ? [filter.field] : []),
+  ];
+  const includeSelf = filter?.includeSelf ?? fieldPaths.length === 0;
+
+  return (payload) => {
+    for (const fieldPath of fieldPaths) {
+      const relationIris = readRelationIris(payload, fieldPath)
+        .map((iri) => normalizeIri(topicMapper.toPayloadIri(iri)));
+      for (const relationIri of relationIris) {
+        const match = findClosestTopic(relationIri, subscribedTopics);
+        if (match) return match;
+      }
+    }
+
+    if (!includeSelf) return undefined;
+
+    const payloadIri = payload['@id'];
+    if (typeof payloadIri !== 'string') return undefined;
+    return findClosestTopic(normalizeIri(topicMapper.toPayloadIri(payloadIri)), subscribedTopics);
+  };
+}
+
+function readRelationIris(payload: Item, path: string): string[] {
+  const value = path
+    .split('.')
+    .filter(Boolean)
+    .reduce<unknown>((current, key) => isIndexable(current) ? current[key] : undefined, payload);
+
+  return extractIris(value);
+}
+
+function extractIris(value: unknown): string[] {
+  if (!value) return [];
+  if (typeof value === 'string') return value.length > 0 ? [value] : [];
+  if (isIndexable(value) && typeof value['@id'] === 'string') return [value['@id']];
+  if (Array.isArray(value)) return value.flatMap(extractIris);
+  return [];
+}
+
+function findClosestTopic(candidate: string, subscribedTopics: string[]): string | undefined {
+  let closest: string | undefined;
+  for (const topic of subscribedTopics) {
+    if (candidate !== topic && !candidate.startsWith(`${topic}/`)) continue;
+    if (!closest || topic.length > closest.length) closest = topic;
+  }
+  return closest;
+}
+
+function normalizeIri(iri: string): string {
+  return iri.endsWith('/') ? iri.slice(0, -1) : iri;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isIndexable(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object';
+}