@obsidiane/meridiane 0.0.6 → 0.0.7

package/templates/_lib_template/src/lib/bridge/sse/mercure.adapter.ts

@@ -1,14 +1,15 @@
-import {DOCUMENT, Inject, Injectable, OnDestroy, PLATFORM_ID} from '@angular/core';
-import {BehaviorSubject, defer, fromEvent, Observable, of, Subject} from 'rxjs';
+import {Inject, Injectable, OnDestroy, Optional, PLATFORM_ID} from '@angular/core';
+import {BehaviorSubject, defer, EMPTY, fromEvent, Observable, of, Subject} from 'rxjs';
 import {auditTime, concatMap, filter, finalize, map, share, takeUntil} from 'rxjs/operators';
-import {API_BASE_URL, MERCURE_CONFIG, MERCURE_HUB_URL} from '../../tokens';
+import {API_BASE_URL, BRIDGE_LOGGER, BRIDGE_WITH_CREDENTIALS, MERCURE_HUB_URL, MERCURE_TOPIC_MODE} from '../../tokens';
+import {BridgeLogger, MercureTopicMode} from '../../bridge.types';
 import {RealtimeEvent, RealtimePort, RealtimeStatus} from '../../ports/realtime.port';
 import {EventSourceWrapper} from './eventsource-wrapper';
-import {Item} from "../../ports/resource-repository.port";
+import {Item} from '../../ports/resource-repository.port';
 import {isPlatformBrowser} from '@angular/common';
 import {MercureUrlBuilder} from './mercure-url.builder';
 import {RefCountTopicRegistry} from './ref-count-topic.registry';
-import {CredentialsPolicy} from '../credentials.policy';
+import {MercureTopicMapper} from './mercure-topic.mapper';
 
 
 @Injectable({providedIn: 'root'})
@@ -19,7 +20,7 @@ export class MercureRealtimeAdapter implements RealtimePort, OnDestroy {
 
   private readonly topicsRegistry = new RefCountTopicRegistry();
   private readonly urlBuilder: MercureUrlBuilder;
-  private readonly credentialsPolicy: CredentialsPolicy;
+  private readonly topicMapper: MercureTopicMapper;
 
   private readonly destroy$ = new Subject<void>();
   private connectionStop$ = new Subject<void>();
@@ -31,13 +32,16 @@ export class MercureRealtimeAdapter implements RealtimePort, OnDestroy {
 
   constructor(
     @Inject(API_BASE_URL) private readonly apiBase: string,
-    @Inject(MERCURE_CONFIG) private readonly init: string,
-    @Inject(MERCURE_HUB_URL) private readonly hubUrl: string,
-    @Inject(DOCUMENT) private readonly doc: Document,
+    @Inject(BRIDGE_WITH_CREDENTIALS) private readonly withCredentialsDefault: boolean,
     @Inject(PLATFORM_ID) private readonly platformId: object,
+    @Optional() @Inject(MERCURE_HUB_URL) private readonly hubUrl?: string,
+    @Optional() @Inject(MERCURE_TOPIC_MODE) topicMode?: MercureTopicMode,
+    @Optional() @Inject(BRIDGE_LOGGER) private readonly logger?: BridgeLogger,
   ) {
-    this.urlBuilder = new MercureUrlBuilder(apiBase);
-    this.credentialsPolicy = new CredentialsPolicy(init);
+    this.urlBuilder = new MercureUrlBuilder();
+    // `topicMode` affects only the `topic=` query param sent to the hub.
+    // Payload IRIs are always matched using same-origin relative IRIs (`/api/...`) when possible.
+    this.topicMapper = new MercureTopicMapper(apiBase, topicMode ?? 'url');
 
     this.rebuild$
       .pipe(
@@ -65,42 +69,54 @@ export class MercureRealtimeAdapter implements RealtimePort, OnDestroy {
 
 
   subscribe$<T>(iris: string[], _filter?: { field?: string }): Observable<RealtimeEvent<T>> {
-    if (iris.length === 0) {
-      return new Observable<RealtimeEvent<T>>((sub) => sub.complete());
-    }
-
-    this.topicsRegistry.addAll(iris);
-    this.scheduleRebuild();
-
-    const filterSet = new Set(iris);
-    const fieldPath = _filter?.field;
+    return defer(() => {
+      const inputIris = iris.filter((v): v is string => typeof v === 'string' && v.length > 0);
+      if (inputIris.length === 0) return EMPTY;
 
-    return this.incoming$.pipe(
-      map((evt) => this.safeParse(evt.data)),
+      if (!this.hubUrl) {
+        this.logger?.debug?.('[Mercure] hubUrl not configured → realtime disabled');
+        return EMPTY;
+      }
 
-      filter((raw: any) => {
-        if (fieldPath) {
-          const relIri = this.extractRelationIris(raw, fieldPath);
-          return Array.from(filterSet).some((iri) => relIri === iri || relIri?.startsWith(`${iri}/`));
-        }
-        const id = raw?.['@id'];
-        return typeof id === 'string' && Array.from(filterSet).some((iri) => {
-          const normalized = iri.endsWith('/') ? iri.slice(0, -1) : iri;
-          return id === normalized || id.startsWith(`${normalized}/`);
-        });
-      }),
-      map((payload) => ({iri: payload['@id'] as string, data: payload as T})),
-      finalize(() => {
-        this.topicsRegistry.removeAll(iris);
-        this.scheduleRebuild();
-      }),
-      share()
-    );
+      // Canonicalise topics (ref-count + URL) to avoid duplicates like:
+      // - "/api/conversations/1" and "http://localhost:8000/api/conversations/1"
+      const registeredTopics = Array.from(new Set(inputIris.map((i) => this.topicMapper.toTopic(i))));
+
+      this.topicsRegistry.addAll(registeredTopics);
+      this.scheduleRebuild();
+
+      // Matching is done against the payload IRIs (typically "/api/...").
+      const subscribed = inputIris.map((i) => normalizeIri(this.topicMapper.toPayloadIri(i)));
+      const fieldPath = _filter?.field;
+
+      return this.incoming$.pipe(
+        map((evt) => this.safeParse(evt.data)),
+        filter((raw): raw is Item => !!raw),
+
+        filter((raw: any) => {
+          if (fieldPath) {
+            const relIris = this.extractRelationIris(raw, fieldPath).map((i) => normalizeIri(this.topicMapper.toPayloadIri(i)));
+            return relIris.some((relIri) => matchesAnySubscribed(relIri, subscribed));
+          }
+          const rawId = raw?.['@id'];
+          const id = typeof rawId === 'string' ? normalizeIri(this.topicMapper.toPayloadIri(rawId)) : undefined;
+          return typeof id === 'string' && matchesAnySubscribed(id, subscribed);
+        }),
+        map((payload) => ({iri: payload['@id'] as string, data: payload as T})),
+        finalize(() => {
+          this.topicsRegistry.removeAll(registeredTopics);
+          this.scheduleRebuild();
+        }),
+        share()
+      );
+    });
   }
 
   unsubscribe(iris: string[]): void {
-    if (!iris || iris.length === 0) return;
-    this.topicsRegistry.removeAll(iris);
+    const inputIris = iris.filter((v): v is string => typeof v === 'string' && v.length > 0);
+    if (inputIris.length === 0) return;
+    const topics = Array.from(new Set(inputIris.map((i) => this.topicMapper.toTopic(i))));
+    this.topicsRegistry.removeAll(topics);
     this.scheduleRebuild();
   }
 
@@ -131,8 +147,14 @@ export class MercureRealtimeAdapter implements RealtimePort, OnDestroy {
       if (this.shuttingDown) return of(void 0);
 
       try {
+        if (!this.hubUrl) {
+          this.currentKey = undefined;
+          this._status$.next('closed');
+          return of(void 0);
+        }
+
         const hasTopics = this.topicsRegistry.hasAny();
-        const key = hasTopics ? this.topicsRegistry.computeKey(this.hubUrl, this.credentialsPolicy.withCredentials()) : undefined;
+        const key = hasTopics ? this.topicsRegistry.computeKey(this.hubUrl, this.withCredentialsDefault) : undefined;
 
         if (!hasTopics) {
           if (this.es) this.teardownConnection();
@@ -148,7 +170,8 @@ export class MercureRealtimeAdapter implements RealtimePort, OnDestroy {
         this.teardownConnection();
 
         const url = this.urlBuilder.build(this.hubUrl, this.topicsRegistry.snapshot(), this.lastEventId);
-        this.es = new EventSourceWrapper(url, {withCredentials: this.credentialsPolicy.withCredentials()});
+        this.logger?.debug?.('[Mercure] connect', {hubUrl: this.hubUrl, topics: this.topicsRegistry.snapshot(), lastEventId: this.lastEventId});
+        this.es = new EventSourceWrapper(url, {withCredentials: this.withCredentialsDefault}, this.logger);
 
         this.connectionStop$ = new Subject<void>();
 
@@ -167,7 +190,7 @@ export class MercureRealtimeAdapter implements RealtimePort, OnDestroy {
         this.es.open();
         this.currentKey = key;
       } catch (err) {
-        console.error('[Mercure] rebuild failed:', err);
+        this.logger?.error?.('[Mercure] rebuild failed:', err);
         this.currentKey = undefined;
         this._status$.next(this.topicsRegistry.hasAny() ? 'connecting' : 'closed');
       }
@@ -195,12 +218,44 @@ export class MercureRealtimeAdapter implements RealtimePort, OnDestroy {
     this._status$.next(this.topicsRegistry.hasAny() ? 'connecting' : 'closed');
   }
 
-  private safeParse(raw: string): Item {
-    return JSON.parse(raw) as Item;
+  private safeParse(raw: string): Item | undefined {
+    try {
+      return JSON.parse(raw) as Item;
+    } catch (err) {
+      this.logger?.debug?.('[Mercure] invalid JSON payload ignored', {raw});
+      return undefined;
+    }
   }
 
-  private extractRelationIris(raw: any, path: string): string {
-    return raw?.[path];
+  private extractRelationIris(raw: any, path: string): string[] {
+    const readPath = (obj: any, dotPath: string): any => {
+      return dotPath
+        .split('.')
+        .filter(Boolean)
+        .reduce((acc, key) => acc?.[key], obj);
+    };
+
+    const normalize = (value: any): string[] => {
+      if (!value) return [];
+      if (typeof value === 'string') return value.length > 0 ? [value] : [];
+      if (typeof value === 'object' && typeof value['@id'] === 'string') return [value['@id']];
+      if (Array.isArray(value)) return value.flatMap(normalize);
+      return [];
+    };
+
+    return normalize(readPath(raw, path));
   }
 
 }
+
+function normalizeIri(iri: string): string {
+  return iri.endsWith('/') ? iri.slice(0, -1) : iri;
+}
+
+function matchesAnySubscribed(candidate: string, subscribed: string[]): boolean {
+  for (const iri of subscribed) {
+    if (candidate === iri) return true;
+    if (candidate.startsWith(`${iri}/`)) return true;
+  }
+  return false;
+}

package/templates/_lib_template/src/lib/bridge/sse/ref-count-topic.registry.ts

@@ -1,43 +1,45 @@
 export class RefCountTopicRegistry {
-  private readonly iris = new Set<string>();
+  private readonly topics = new Set<string>();
   private readonly refCounts = new Map<string, number>();
 
-
-  addAll(iris: Iterable<string>): void {
-    for (const iri of iris) {
-      const next = (this.refCounts.get(iri) ?? 0) + 1;
-      this.refCounts.set(iri, next);
-      this.iris.add(iri);
+  /**
+   * Increments ref-count for each topic.
+   * Callers should pass unique topic strings (deduped).
+   */
+  addAll(topics: Iterable<string>): void {
+    for (const topic of topics) {
+      const next = (this.refCounts.get(topic) ?? 0) + 1;
+      this.refCounts.set(topic, next);
+      this.topics.add(topic);
     }
   }
 
-
-  removeAll(iris: Iterable<string>): void {
-    for (const iri of iris) {
-      const next = (this.refCounts.get(iri) ?? 0) - 1;
+  /**
+   * Decrements ref-count for each topic.
+   * Callers should pass unique topic strings (deduped).
+   */
+  removeAll(topics: Iterable<string>): void {
+    for (const topic of topics) {
+      const next = (this.refCounts.get(topic) ?? 0) - 1;
       if (next <= 0) {
-        this.refCounts.delete(iri);
-        this.iris.delete(iri);
+        this.refCounts.delete(topic);
+        this.topics.delete(topic);
       } else {
-        this.refCounts.set(iri, next);
+        this.refCounts.set(topic, next);
       }
     }
   }
 
-
   hasAny(): boolean {
-    return this.iris.size > 0;
+    return this.topics.size > 0;
   }
 
-
   snapshot(): ReadonlySet<string> {
-    return new Set(this.iris);
+    return new Set(this.topics);
   }
 
-
-
   computeKey(hubUrl: string, credentialsOn: boolean): string {
-    const topicsSorted = Array.from(this.iris).sort().join('|');
+    const topicsSorted = Array.from(this.topics).sort().join('|');
     return `${hubUrl}::${credentialsOn ? '1' : '0'}::${topicsSorted}`;
   }
 }

package/templates/_lib_template/src/lib/bridge.types.ts

@@ -0,0 +1,33 @@
+/**
+ * Public configuration types for the bridge.
+ *
+ * Keep this file dependency-free (no Angular imports) so it can be used from both
+ * runtime code and type-only contexts.
+ */
+
+export interface BridgeLogger {
+  debug: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+}
+
+export interface BridgeDefaults {
+  headers?: Record<string, string>;
+  timeoutMs?: number;
+  retries?:
+    | number
+    | {
+        count: number;
+        delayMs?: number;
+        methods?: string[];
+      };
+}
+
+/**
+ * Controls how Mercure topics are sent in the hub URL.
+ * - `url`: topics are absolute URLs (recommended default)
+ * - `iri`: topics are same-origin relative IRIs (e.g. `/api/...`)
+ */
+export type MercureTopicMode = 'url' | 'iri';
+

package/templates/_lib_template/src/lib/facades/bridge.facade.ts

@@ -0,0 +1,116 @@
+import {Inject, Injectable} from '@angular/core';
+import {HttpClient} from '@angular/common/http';
+import {Observable} from 'rxjs';
+import {filter, map, share} from 'rxjs/operators';
+import {toHttpParams} from '../bridge/rest/query-builder';
+import {MercureRealtimeAdapter} from '../bridge/sse/mercure.adapter';
+import {API_BASE_URL, BRIDGE_WITH_CREDENTIALS} from '../tokens';
+import {AnyQuery, Collection, HttpCallOptions, HttpRequestConfig, Iri, IriRequired, Item} from '../ports/resource-repository.port';
+import {SubscribeFilter} from '../ports/realtime.port';
+import {resolveUrl} from '../utils/url';
+
+/**
+ * High-level facade for ad-hoc HTTP calls and Mercure subscriptions.
+ *
+ * Prefer `FacadeFactory` + `ResourceFacade<T>` when you want a resource-oriented API.
+ */
+@Injectable({providedIn: 'root'})
+export class BridgeFacade {
+  constructor(
+    private readonly http: HttpClient,
+    private readonly realtime: MercureRealtimeAdapter,
+    @Inject(API_BASE_URL) private readonly apiBase: string,
+    @Inject(BRIDGE_WITH_CREDENTIALS) private readonly withCredentialsDefault: boolean,
+  ) {
+  }
+
+  // ──────────────── HTTP ────────────────
+
+  get$<R = unknown>(url: IriRequired, opts?: HttpCallOptions): Observable<R> {
+    return this.http.get<R>(this.resolveUrl(url), {
+      headers: opts?.headers,
+      withCredentials: opts?.withCredentials ?? this.withCredentialsDefault,
+    });
+  }
+
+  getCollection$<T extends Item = Item>(
+    url: IriRequired,
+    query?: AnyQuery,
+    opts?: HttpCallOptions
+  ): Observable<Collection<T>> {
+    const params = toHttpParams(query);
+    return this.http.get<Collection<T>>(this.resolveUrl(url), {
+      params,
+      headers: opts?.headers,
+      withCredentials: opts?.withCredentials ?? this.withCredentialsDefault,
+    });
+  }
+
+  post$<R = unknown, B = unknown>(url: IriRequired, payload: B, opts?: HttpCallOptions): Observable<R> {
+    return this.http.post<R>(this.resolveUrl(url), payload, {
+      headers: opts?.headers,
+      withCredentials: opts?.withCredentials ?? this.withCredentialsDefault,
+    });
+  }
+
+  patch$<R = unknown, B = unknown>(url: IriRequired, changes: B, opts?: HttpCallOptions): Observable<R> {
+    return this.http.patch<R>(this.resolveUrl(url), changes, {
+      headers: opts?.headers,
+      withCredentials: opts?.withCredentials ?? this.withCredentialsDefault,
+    });
+  }
+
+  put$<R = unknown, B = unknown>(url: IriRequired, payload: B, opts?: HttpCallOptions): Observable<R> {
+    return this.http.put<R>(this.resolveUrl(url), payload, {
+      headers: opts?.headers,
+      withCredentials: opts?.withCredentials ?? this.withCredentialsDefault,
+    });
+  }
+
+  delete$(url: IriRequired, opts?: HttpCallOptions): Observable<void> {
+    return this.http.delete<void>(this.resolveUrl(url), {
+      headers: opts?.headers,
+      withCredentials: opts?.withCredentials ?? this.withCredentialsDefault,
+    });
+  }
+
+  request$<R = unknown, B = unknown>(req: HttpRequestConfig<B>): Observable<R> {
+    const {method, url, query, body, headers, responseType, withCredentials, options = {}} = req;
+    const targetUrl = this.resolveUrl(url);
+
+    const mergedOptions: Record<string, unknown> = {...options};
+    if (headers) mergedOptions['headers'] = headers;
+    if (query) mergedOptions['params'] = toHttpParams(query);
+    if (body !== undefined) mergedOptions['body'] = body;
+
+    mergedOptions['responseType'] = (responseType ?? (mergedOptions['responseType'] as any) ?? 'json') as any;
+    mergedOptions['withCredentials'] =
+      withCredentials ?? (mergedOptions['withCredentials'] as any) ?? this.withCredentialsDefault;
+    mergedOptions['observe'] = 'body';
+
+    return this.http.request<R>(method, targetUrl, mergedOptions as {observe: 'body'});
+  }
+
+  // ──────────────── SSE / Mercure ────────────────
+
+  watch$<T = Item>(iri: Iri | Iri[], subscribeFilter?: SubscribeFilter): Observable<T> {
+    const iris = (Array.isArray(iri) ? iri : [iri]).filter((v): v is string => typeof v === 'string' && v.length > 0);
+    return this.realtime
+      .subscribe$<T>(iris, subscribeFilter)
+      .pipe(
+        map((event) => event.data),
+        filter((data): data is T => data !== undefined),
+        share()
+      );
+  }
+
+  unwatch(iri: Iri | Iri[]): void {
+    const iris = (Array.isArray(iri) ? iri : [iri]).filter((v): v is string => typeof v === 'string' && v.length > 0);
+    this.realtime.unsubscribe(iris);
+  }
+
+  private resolveUrl(path?: Iri): string {
+    if (!path) throw new Error('BridgeFacade: missing url');
+    return resolveUrl(this.apiBase, path);
+  }
+}

package/templates/_lib_template/src/lib/facades/facade.factory.ts

@@ -1,11 +1,11 @@
-import {Injectable, Inject, runInInjectionContext, inject, EnvironmentInjector} from '@angular/core';
+import {EnvironmentInjector, inject, Injectable, runInInjectionContext} from '@angular/core';
 import {HttpClient} from '@angular/common/http';
 import {RealtimePort} from '../ports/realtime.port';
 import {Item, ResourceRepository} from '../ports/resource-repository.port';
-import {API_BASE_URL, MERCURE_CONFIG} from "../tokens";
-import {MercureRealtimeAdapter} from "../bridge/sse/mercure.adapter";
-import {ApiPlatformRestRepository} from "../bridge/rest/api-platform.adapter";
-import {ResourceFacade} from "./resource.facade";
+import {API_BASE_URL, BRIDGE_WITH_CREDENTIALS} from '../tokens';
+import {MercureRealtimeAdapter} from '../bridge/sse/mercure.adapter';
+import {ApiPlatformRestRepository} from '../bridge/rest/api-platform.adapter';
+import {ResourceFacade} from './resource.facade';
 
 export type FacadeConfig<T> = {
   url: string;
@@ -16,21 +16,23 @@ export type FacadeConfig<T> = {
 
 @Injectable({providedIn: 'root'})
 export class FacadeFactory {
+  private readonly env = inject(EnvironmentInjector);
+  private readonly http = inject(HttpClient);
+  private readonly baseUrl = inject(API_BASE_URL);
+  private readonly withCredentials = inject(BRIDGE_WITH_CREDENTIALS);
+  private readonly mercure = inject(MercureRealtimeAdapter);
 
-  private env = inject(EnvironmentInjector);
-
-  constructor(
-    private readonly http: HttpClient,
-    @Inject(API_BASE_URL) private readonly baseUrl: string,
-    @Inject(MERCURE_CONFIG) private readonly init: string,
-    private readonly mercureAny: MercureRealtimeAdapter
-  ) {
-  }
-
+  /**
+   * Creates a `ResourceFacade<T>`.
+   *
+   * Important: `ResourceFacade` uses `toSignal()`, which requires an injection context.
+   * This factory ensures that by using `runInInjectionContext`.
+   */
   create<T extends Item>(config: FacadeConfig<T>): ResourceFacade<T> {
-    const path = config.url;
-    const repo = new ApiPlatformRestRepository<T>(this.http, this.baseUrl, path , this.init);
-    const realtime = this.mercureAny as MercureRealtimeAdapter;
-    return runInInjectionContext(this.env, () => new ResourceFacade<T>(repo, realtime, path));
+    const url = config.url;
+    const repo = config.repo ?? new ApiPlatformRestRepository<T>(this.http, this.baseUrl, url, this.withCredentials);
+    const realtime = config.realtime ?? this.mercure;
+
+    return runInInjectionContext(this.env, () => new ResourceFacade<T>(repo, realtime));
   }
 }

package/templates/_lib_template/src/lib/facades/facade.interface.ts

@@ -1,35 +1,30 @@
 import {
   Collection,
-  CreateCommand,
   HttpRequestConfig,
   Iri,
+  IriRequired,
   Item,
-  Query,
-  UpdateCommand
-} from "../ports/resource-repository.port";
-import {Observable} from "rxjs";
+  HttpCallOptions,
+  AnyQuery,
+} from '../ports/resource-repository.port';
+import {Observable} from 'rxjs';
 
 export interface Facade<T extends Item> {
+  getCollection$(query?: AnyQuery, opts?: HttpCallOptions): Observable<Collection<T>>;
 
-  list$(query?: Query): Observable<Collection<T>>;
+  get$(iri: IriRequired, opts?: HttpCallOptions): Observable<T>;
 
-  get$(iri: Iri): Observable<T>;
+  post$(payload: Partial<T>, opts?: HttpCallOptions): Observable<T>;
 
-  create$(cmd: CreateCommand<T>): Observable<T>;
+  patch$(iri: IriRequired, changes: Partial<T>, opts?: HttpCallOptions): Observable<T>;
 
-  update$(cmd: UpdateCommand<T>): Observable<T>;
+  put$(iri: IriRequired, payload: Partial<T>, opts?: HttpCallOptions): Observable<T>;
 
-  delete$(iri: Iri): Observable<void>;
-
-  post$<R = unknown, B = unknown>(req: RestRequest<B>): Observable<R>;
-  put$<R = unknown, B = unknown>(req: RestRequest<B>): Observable<R>;
-  patch$<R = unknown, B = unknown>(req: RestRequest<B>): Observable<R>;
+  delete$(iri: IriRequired, opts?: HttpCallOptions): Observable<void>;
 
   request$<R = unknown, B = unknown>(req: HttpRequestConfig<B>): Observable<R>;
 
-  watch$(iri: Iri|Iri[]): Observable<T>;
+  watch$(iri: Iri | Iri[]): Observable<T>;
 
-  unwatch(iri: Iri|Iri[]): void;
+  unwatch(iri: Iri | Iri[]): void;
 }
-
-export type RestRequest<B> = Omit<HttpRequestConfig<B>, 'method'>;