@obsidiane/meridiane 0.0.6

package/README.md

@@ -0,0 +1,60 @@
+# @obsidiane/meridiane
+
+CLI pour générer une librairie Angular “bridge” (Symfony / API Platform / Mercure) et générer des modèles TypeScript depuis une spec OpenAPI.
+
+## Installation
+
+```bash
+npm i -D @obsidiane/meridiane
+```
+
+Ou en global :
+
+```bash
+npm i -g @obsidiane/meridiane
+```
+
+## Usage
+
+```bash
+# Générer une librairie Angular (dans projects/<lib-name>)
+npx meridiane lib <lib-name> <npm-package-name> [version] [url-registry]
+
+# Générer des modèles depuis OpenAPI
+npx meridiane models <SPEC_OPENAPI_URL_OU_FICHIER_JSON> [--out=<dir>] [--item-import=../lib/ports/resource-repository.port] [--required-mode=all-optional|spec] [--no-index]
+```
+
+`url-registry` est optionnel. Recommandé : gérer le registry via `.npmrc` / variables CI plutôt que de le passer au générateur.
+
+## Exemple CI (générer + build + publish)
+
+```bash
+npm ci
+npx -y @obsidiane/meridiane@0.1.0 lib backend-bridge @acme/backend-bridge 0.1.0
+npx -y @obsidiane/meridiane@0.1.0 models http://localhost:8000/api/docs.json --out=projects/backend-bridge/src/models
+npx ng build backend-bridge
+cd dist/backend-bridge
+npm publish
+```
+
+Si votre workspace ne contient pas `ng-packagr` (souvent le cas dans une app Angular “pure”), installez-le :
+
+```bash
+npm i -D ng-packagr
+```
+
+## Configuration (models.config.js)
+
+Le générateur de modèles charge automatiquement un fichier `models.config.js` s’il existe dans le répertoire courant (CWD).
+
+Copie rapide (après installation) :
+
+```bash
+cp node_modules/@obsidiane/meridiane/models.config.example.js ./models.config.js
+```
+
+Sans installation préalable :
+
+```bash
+npx -y @obsidiane/meridiane lib <lib-name> <npm-package-name> [version] [url-registry]
+```

package/cli.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import {fileURLToPath} from 'node:url';
+import path from 'node:path';
+import {spawn} from 'node:child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function runTool(scriptName, args) {
+  const scriptPath = path.join(__dirname, 'tools', scriptName);
+  const child = spawn(process.execPath, [scriptPath, ...args], {
+    stdio: 'inherit',
+  });
+
+  child.on('exit', (code) => {
+    process.exit(code ?? 0);
+  });
+}
+
+function printHelp() {
+  console.log(`
+Usage:
+  meridiane lib <lib-name> <npm-package-name> [version] [url-registry]
+  meridiane models <SPEC_OPENAPI_URL_OU_FICHIER_JSON> [options]
+
+Examples:
+  npx -y @obsidiane/meridiane lib backend-bridge @acme/backend-bridge 0.1.0
+  npx -y @obsidiane/meridiane models http://localhost:8000/api/docs.json --out=projects/backend-bridge/src/models
+`);
+}
+
+const [, , cmd, ...rest] = process.argv;
+
+switch (cmd) {
+  case 'lib':
+    runTool('generate-lib.js', rest);
+    break;
+  case 'models':
+    runTool('generate-models.js', rest);
+    break;
+  case '-h':
+  case '--help':
+  case undefined:
+    printHelp();
+    break;
+  default:
+    console.error(`Unknown command: ${cmd}`);
+    printHelp();
+    process.exit(1);
+}

package/models.config.example.js

@@ -0,0 +1,24 @@
+// Exemple de configuration pour la génération des modèles.
+// Copiez ce fichier en `models.config.js` dans le dossier où vous lancez la commande (`meridiane models`).
+// Format CommonJS pour éviter les warnings Node dans la plupart des workspaces Angular.
+
+module.exports = {
+  // Dossier de sortie (relatif au CWD)
+  outDir: 'projects/backend-bridge/src/models',
+
+  // Chemin d'import de `Item` dans les templates (relatif au fichier généré)
+  itemImportPath: '../lib/ports/resource-repository.port',
+
+  // Contrôle des propriétés optionnelles
+  // - 'all-optional': toutes les props sont optionnelles
+  // - 'spec': respecte le tableau `required` de la spec
+  requiredMode: 'all-optional',
+
+  // Préférence entre variantes de schémas (.jsonld, .jsonapi ou aucune)
+  // Valeurs possibles: 'jsonld' | 'jsonapi' | 'none'
+  preferFlavor: 'jsonld',
+
+  // Hydra: regex pour les schémas de base à ignorer (merge allOf / filtrage)
+  // Peut être une RegExp ou une string passée à `new RegExp(...)`
+  hydraBaseRegex: /^Hydra(?:Item|Collection)BaseSchema$/,
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@obsidiane/meridiane",
+  "version": "0.0.6",
+  "description": "Générateur de librairie Angular et modèles TypeScript (OpenAPI) pour un bridge Symfony/API Platform + Mercure.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/obsidiane-lab/meridiane"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "pack:check": "npm_config_cache=./.npm-cache npm pack --dry-run"
+  },
+  "bin": {
+    "meridiane": "cli.js",
+    "meridiane-generate-lib": "tools/generate-lib.js",
+    "meridiane-generate-models": "tools/generate-models.js"
+  },
+  "files": [
+    "cli.js",
+    "tools/**",
+    "templates/**",
+    "models.config.example.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "fs-extra": "^11.3.1",
+    "handlebars": "^4.7.8",
+    "openapi-typescript-codegen": "^0.29.0",
+    "tslib": "^2.3.0"
+  }
+}

package/templates/_lib_template/ng-package.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "../../dist/__LIB_NAME__",
+  "lib": {
+    "entryFile": "src/public-api.ts"
+  }
+}

package/templates/_lib_template/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "__LIB_NAME__",
+  "version": "0.0.1",
+  "peerDependencies": {
+    "@angular/common": "^20.1.0",
+    "@angular/core": "^20.1.0"
+  },
+  "dependencies": {
+    "tslib": "^2.8.1"
+  },
+  "sideEffects": false
+}

package/templates/_lib_template/src/lib/bridge/credentials.policy.ts

@@ -0,0 +1,9 @@
+export class CredentialsPolicy {
+  constructor(private readonly init: unknown) {
+  }
+
+  withCredentials(): boolean {
+    const c = this.init as any;
+    return c?.withCredentials === true || c?.credentials === 'include';
+  }
+}

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

@@ -0,0 +1,101 @@
+import {HttpClient} from '@angular/common/http';
+import {Observable} from 'rxjs';
+import {toHttpParams} from './query-builder';
+import {
+  Collection,
+  CreateCommand,
+  HttpRequestConfig,
+  Iri, Item,
+  Query,
+  ResourceRepository,
+  UpdateCommand
+} from '../../ports/resource-repository.port';
+import {CredentialsPolicy} from '../credentials.policy';
+
+
+export class ApiPlatformRestRepository<T extends Item> implements ResourceRepository<T> {
+  private readonly credentialsPolicy: CredentialsPolicy;
+
+  constructor(
+    private readonly http: HttpClient,
+    private readonly apiBase: string,
+    private readonly resourcePath: Iri,
+    readonly init: string,
+  ) {
+    this.credentialsPolicy = new CredentialsPolicy(init);
+  }
+
+  list$(query?: Query): Observable<Collection<T>> {
+    return this.http.get<any>(`${this.apiBase}${this.resourcePath}`, {
+      params: toHttpParams(query),
+      withCredentials: this.credentialsPolicy.withCredentials()
+    });
+  }
+
+  get$(iri: Iri): Observable<T> {
+    return this.http.get<T>(`${this.apiBase}${iri}`, {
+      withCredentials: this.credentialsPolicy.withCredentials()
+    });
+  }
+
+  create$(cmd: CreateCommand<T>): Observable<T> {
+    return this.http.post<T>(`${this.apiBase}${this.resourcePath}`, cmd.payload, {
+      withCredentials: this.credentialsPolicy.withCredentials()
+    });
+  }
+
+  update$(cmd: UpdateCommand<T>): Observable<T> {
+    return this.http.patch<T>(`${this.apiBase}${cmd.iri}`, cmd.changes, {
+      withCredentials: this.credentialsPolicy.withCredentials()
+    });
+  }
+
+  delete$(iri: Iri): Observable<void> {
+    return this.http.delete<void>(`${this.apiBase}${iri}`, {
+      withCredentials: this.credentialsPolicy.withCredentials()
+    });
+  }
+
+  request$<R = unknown, B = unknown>(req: HttpRequestConfig<B>): Observable<R> {
+    const {
+      method,
+      url,
+      query,
+      body,
+      headers,
+      responseType,
+      withCredentials,
+      options = {}
+    } = req;
+
+    const mergedOptions: any = {...options};
+    const targetUrl = this.resolveUrl(url ?? this.resourcePath);
+
+    const computedResponseType = responseType ?? mergedOptions.responseType ?? 'json';
+    mergedOptions.responseType = computedResponseType as any;
+
+    const credentials = withCredentials ?? mergedOptions.withCredentials ?? this.credentialsPolicy.withCredentials();
+    mergedOptions.withCredentials = credentials;
+
+    if (headers) mergedOptions.headers = headers;
+    if (query) mergedOptions.params = toHttpParams(query as any);
+    if (body !== undefined) mergedOptions.body = body;
+
+    mergedOptions.observe = 'body';
+    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.resolveUrl: missing url and resourcePath');
+    if (/^https?:\/\//i.test(effectivePath)) return effectivePath;
+    if (effectivePath.startsWith('//')) return effectivePath;
+    return joinUrl(this.apiBase, effectivePath);
+  }
+}
+
+function joinUrl(base: string, path: string): string {
+  const normalizedBase = base.endsWith('/') ? base.slice(0, -1) : base;
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+  return `${normalizedBase}${normalizedPath}`;
+}

package/templates/_lib_template/src/lib/bridge/rest/query-builder.ts

@@ -0,0 +1,43 @@
+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;
+
+    const fromObject: Record<string, string | string[]> = {};
+
+    const consumed = new Set<string>();
+    const maybeQuery = q as Query;
+    if (maybeQuery.page != null) {
+        fromObject['page'] = String(maybeQuery.page);
+        consumed.add('page');
+    }
+    if (maybeQuery.itemsPerPage != null) {
+        fromObject['itemsPerPage'] = String(maybeQuery.itemsPerPage);
+        consumed.add('itemsPerPage');
+    }
+
+    if (q.filters) {
+        consumed.add('filters');
+        for (const [k, v] of Object.entries(q.filters)) {
+            assign(fromObject, k, v);
+        }
+    }
+
+    for (const [k, v] of Object.entries(q as Record<string, QueryParamValue>)) {
+        if (consumed.has(k)) continue;
+        assign(fromObject, k, v);
+    }
+
+    return new HttpParams({fromObject});
+}
+
+function assign(target: Record<string, string | string[]>, key: string, value: QueryParamValue | undefined) {
+    if (value == null) return;
+    if (Array.isArray(value)) {
+        target[key] = value.map(String);
+    } else {
+        target[key] = String(value);
+    }
+}

package/templates/_lib_template/src/lib/bridge/sse/eventsource-wrapper.ts

@@ -0,0 +1,74 @@
+import {ReplaySubject, Subject} from 'rxjs';
+import {SseEvent, SseOptions, RealtimeStatus} from '../../ports/realtime.port';
+
+export class EventSourceWrapper {
+    private es?: EventSource;
+
+    private readonly statusSub = new ReplaySubject<RealtimeStatus>(1);
+    private readonly eventSub = new Subject<SseEvent>();
+
+    readonly status$ = this.statusSub.asObservable();
+    readonly events$ = this.eventSub.asObservable();
+
+    /** Activer pour conversations local */
+    private readonly debug = false;
+
+    constructor(
+        private readonly url: string,
+        private readonly opts: SseOptions = {}
+    ) {
+        this.setState('closed');
+        this.log('[SSE] initialized', url, opts);
+    }
+
+    open(): void {
+        if (this.es) {
+            this.log('[SSE] open() ignored: already open');
+            return;
+        }
+
+        this.setState('connecting');
+        this.log('[SSE] creating EventSource');
+
+        const es = new EventSource(this.url, {
+            withCredentials: !!this.opts.withCredentials,
+        });
+        this.es = es;
+
+        es.onopen = () => {
+            this.setState('connected');
+        };
+
+        es.onmessage = (ev) => {
+            this.log('[SSE] event', ev);
+            this.log('[SSE] message', ev.data);
+            this.eventSub.next({type: 'message', data: ev.data, lastEventId: ev.lastEventId || undefined});
+        };
+
+        es.onerror = () => {
+            // Le navigateur va retenter. On reste en "connecting".
+            this.log('[SSE] error → retrying (browser)');
+            this.setState('connecting');
+        };
+    }
+
+    close(): void {
+        if (this.es) {
+            this.es.close();
+            this.es = undefined;
+            this.log('[SSE] closed');
+        }
+        this.setState('closed');
+    }
+
+    // ──────────────── internals ────────────────
+
+    private setState(state: RealtimeStatus): void {
+        this.log('[SSE] state', state);
+        this.statusSub.next(state);
+    }
+
+    private log(...args: unknown[]): void {
+        if (this.debug) console.log(...args);
+    }
+}

package/templates/_lib_template/src/lib/bridge/sse/mercure-url.builder.ts

@@ -0,0 +1,17 @@
+export class MercureUrlBuilder {
+  constructor(private readonly apiBase: string) {
+  }
+
+
+  build(hubUrl: string, iris: ReadonlySet<string>, lastEventId?: string): string {
+    const url = new URL(hubUrl);
+    if (lastEventId) {
+      url.searchParams.set('lastEventID', lastEventId);
+    }
+    url.searchParams.delete('topic');
+    for (const iri of iris) {
+      url.searchParams.append('topic', this.apiBase + iri);
+    }
+    return url.toString();
+  }
+}

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

@@ -0,0 +1,206 @@
+import {DOCUMENT, Inject, Injectable, OnDestroy, PLATFORM_ID} from '@angular/core';
+import {BehaviorSubject, defer, 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 {RealtimeEvent, RealtimePort, RealtimeStatus} from '../../ports/realtime.port';
+import {EventSourceWrapper} from './eventsource-wrapper';
+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';
+
+
+@Injectable({providedIn: 'root'})
+export class MercureRealtimeAdapter implements RealtimePort, OnDestroy {
+  private lastEventId?: string;
+  private es?: EventSourceWrapper;
+  private currentKey?: string;
+
+  private readonly topicsRegistry = new RefCountTopicRegistry();
+  private readonly urlBuilder: MercureUrlBuilder;
+  private readonly credentialsPolicy: CredentialsPolicy;
+
+  private readonly destroy$ = new Subject<void>();
+  private connectionStop$ = new Subject<void>();
+  private readonly rebuild$ = new Subject<void>();
+  private shuttingDown = false;
+
+  private readonly _status$ = new BehaviorSubject<RealtimeStatus>('closed');
+  private readonly incoming$ = new Subject<{ type: string; data: string }>();
+
+  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(PLATFORM_ID) private readonly platformId: object,
+  ) {
+    this.urlBuilder = new MercureUrlBuilder(apiBase);
+    this.credentialsPolicy = new CredentialsPolicy(init);
+
+    this.rebuild$
+      .pipe(
+        auditTime(10),
+        concatMap(() => this.rebuildOnce$()),
+      )
+      .subscribe();
+
+    if (isPlatformBrowser(this.platformId)) {
+      fromEvent<PageTransitionEvent>(window, 'pagehide')
+        .pipe(takeUntil(this.destroy$))
+        .subscribe(() => this.shutdownBeforeExit());
+
+      fromEvent<BeforeUnloadEvent>(window, 'beforeunload')
+        .pipe(takeUntil(this.destroy$))
+        .subscribe(() => this.shutdownBeforeExit());
+    }
+  }
+
+  // ──────────────── API publique ────────────────
+
+  status$(): Observable<RealtimeStatus> {
+    return this._status$.asObservable();
+  }
+
+
+  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 this.incoming$.pipe(
+      map((evt) => this.safeParse(evt.data)),
+
+      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()
+    );
+  }
+
+  unsubscribe(iris: string[]): void {
+    if (!iris || iris.length === 0) return;
+    this.topicsRegistry.removeAll(iris);
+    this.scheduleRebuild();
+  }
+
+  public shutdownBeforeExit(): void {
+    if (this.shuttingDown) return;
+    this.shuttingDown = true;
+    this.teardownConnection();
+  }
+
+  ngOnDestroy(): void {
+    this.teardownConnection();
+    this._status$.complete();
+    this.incoming$.complete();
+    this.destroy$.next();
+    this.destroy$.complete();
+    this.rebuild$.complete();
+  }
+
+  // ───────────────── PRIVATE ─────────────────
+
+  private scheduleRebuild(): void {
+    if (this.shuttingDown) return;
+    this.rebuild$.next();
+  }
+
+  private rebuildOnce$() {
+    return defer(() => {
+      if (this.shuttingDown) return of(void 0);
+
+      try {
+        const hasTopics = this.topicsRegistry.hasAny();
+        const key = hasTopics ? this.topicsRegistry.computeKey(this.hubUrl, this.credentialsPolicy.withCredentials()) : undefined;
+
+        if (!hasTopics) {
+          if (this.es) this.teardownConnection();
+          this.currentKey = undefined;
+          this._status$.next('closed');
+          return of(void 0);
+        }
+
+        if (key && key === this.currentKey) {
+          return of(void 0);
+        }
+
+        this.teardownConnection();
+
+        const url = this.urlBuilder.build(this.hubUrl, this.topicsRegistry.snapshot(), this.lastEventId);
+        this.es = new EventSourceWrapper(url, {withCredentials: this.credentialsPolicy.withCredentials()});
+
+        this.connectionStop$ = new Subject<void>();
+
+        this.es.status$
+          .pipe(takeUntil(this.connectionStop$), takeUntil(this.destroy$))
+          .subscribe((st) => this.updateGlobalStatus(st));
+
+        this.es.events$
+          .pipe(takeUntil(this.connectionStop$), takeUntil(this.destroy$))
+          .subscribe((e) => {
+            this.lastEventId = e.lastEventId ?? this.lastEventId;
+            this.incoming$.next(e);
+          });
+
+        this._status$.next('connecting');
+        this.es.open();
+        this.currentKey = key;
+      } catch (err) {
+        console.error('[Mercure] rebuild failed:', err);
+        this.currentKey = undefined;
+        this._status$.next(this.topicsRegistry.hasAny() ? 'connecting' : 'closed');
+      }
+
+      return of(void 0);
+    });
+  }
+
+  private teardownConnection(): void {
+    this.es?.close();
+    this.es = undefined;
+    this.connectionStop$.next();
+    this.connectionStop$.complete();
+  }
+
+  private updateGlobalStatus(sse: RealtimeStatus): void {
+    if (sse === 'connected') {
+      this._status$.next('connected');
+      return;
+    }
+    if (sse === 'connecting') {
+      this._status$.next('connecting');
+      return;
+    }
+    this._status$.next(this.topicsRegistry.hasAny() ? 'connecting' : 'closed');
+  }
+
+  private safeParse(raw: string): Item {
+    return JSON.parse(raw) as Item;
+  }
+
+  private extractRelationIris(raw: any, path: string): string {
+    return raw?.[path];
+  }
+
+}

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

@@ -0,0 +1,43 @@
+export class RefCountTopicRegistry {
+  private readonly iris = 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);
+    }
+  }
+
+
+  removeAll(iris: Iterable<string>): void {
+    for (const iri of iris) {
+      const next = (this.refCounts.get(iri) ?? 0) - 1;
+      if (next <= 0) {
+        this.refCounts.delete(iri);
+        this.iris.delete(iri);
+      } else {
+        this.refCounts.set(iri, next);
+      }
+    }
+  }
+
+
+  hasAny(): boolean {
+    return this.iris.size > 0;
+  }
+
+
+  snapshot(): ReadonlySet<string> {
+    return new Set(this.iris);
+  }
+
+
+
+  computeKey(hubUrl: string, credentialsOn: boolean): string {
+    const topicsSorted = Array.from(this.iris).sort().join('|');
+    return `${hubUrl}::${credentialsOn ? '1' : '0'}::${topicsSorted}`;
+  }
+}