@obsidiane/meridiane 2.0.5 → 2.0.7

package/README.md

@@ -1,8 +1,8 @@
 # @obsidiane/meridiane
 
-CLI pour générer un bridge Angular (API Platform + Mercure) depuis une spec OpenAPI.
+CLI pour générer un bridge Angular (runtime + models TypeScript) depuis une spec OpenAPI (API Platform + Mercure).
 
-Documentation complète (repo) : `docs/guide-bridge.md`.
+Documentation complète du repo : `docs/guide-bridge.md`.
 
 ## Installation
 
@@ -10,17 +10,11 @@ Documentation complète (repo) : `docs/guide-bridge.md`.
 npm i -D @obsidiane/meridiane
 ```
 
-Ou en global :
-
-```bash
-npm i -g @obsidiane/meridiane
-```
-
 ## Commandes
 
 ### `meridiane generate <packageName>`
 
-Génère uniquement les fichiers du bridge dans le workspace courant (pas de build, pas de `npm pack`).
+Génère uniquement les sources du bridge dans le workspace courant.
 
 ```bash
 npx meridiane generate @acme/backend-bridge --spec ./openapi.json
@@ -30,7 +24,7 @@ Sortie par défaut : `projects/<libName>/` (modifiable via `--out`).
 
 ### `meridiane dev [packageName]`
 
-Build standalone + installation locale dans `node_modules`.
+Génération + build standalone + `npm pack` + installation locale dans `node_modules`.
 
 ```bash
 npx meridiane dev @acme/backend-bridge --spec http://localhost:8000/api/docs.json
@@ -42,10 +36,10 @@ Sorties :
 
 ### `meridiane build <packageName>`
 
-Build standalone + `npm pack` (artefact publiable).
+Génération + build standalone + `npm pack` (artefact publiable).
 
 ```bash
-npx meridiane build @acme/backend-bridge --version 0.1.0 --spec https://staging.example/api/docs.json
+npx meridiane build @acme/backend-bridge --version 1.2.3 --spec https://staging.example/api/docs.json
 ```
 
 Sorties :
@@ -54,20 +48,21 @@ Sorties :
 
 ## Options
 
-- `--spec <url|file>` : source OpenAPI (URL ou fichier JSON local) ; requis sauf `--no-models`.
-- `--formats <mimeTypes>` : répétable ou liste `,` (ordre significatif). Active le mode contract-driven.
-- `--include/--exclude <substr>` : filtrer des noms de schémas OpenAPI.
-- `--no-models` : ne génère que le runtime (pas de models).
-- `--version <semver>` : version écrite dans le `package.json` (`build` + `generate`).
-- `--out <dir>` : répertoire de sortie pour `generate` (défaut `projects/<libName>`).
-- `--debug` : logs détaillés.
+- `--spec <url|file>` : URL OpenAPI ou fichier JSON local (requis sauf `--no-models`)
+- `--formats <mimeTypes>` : répétable ou liste `,` ; défaut `application/ld+json`
+- `--include <substr>` / `--exclude <substr>` : filtres de noms de schémas (répétables, support `,`)
+- `--no-models` : runtime only
+- `--version <semver>` : `build` et `generate` (défaut `0.0.0`)
+- `--out <dir>` : uniquement `generate`
+- `--debug` : logs détaillés
 
 ## Notes importantes
 
-- `--formats` active un mode contract-driven : seuls les schemas réellement utilisés par les endpoints/paths sont générés.
-- Les modèles `*.jsonMergePatch` ne sont jamais générés (`PATCH` est typé en `Partial<T>`).
-- Meridiane **ne publie pas** : utilisez `npm publish` côté CI.
+- fallback automatique `.../api/docs.json` -> `.../api/docs.jsonopenapi` si nécessaire
+- mode contract-driven : uniquement les schémas atteignables via `paths` pour les formats sélectionnés
+- modèles `*jsonMergePatch*` non générés (`PATCH` typé `Partial<T>`)
+- Meridiane ne publie pas : publication via `npm publish` côté CI
 
-## Note (repo Meridiane)
+## Spécifique à ce repo
 
-Dans ce repo, `meridiane dev` peut être exécutée sans `packageName` et cible l’app sandbox (`apps/sandbox`).
+Dans ce monorepo, `meridiane dev` peut être exécuté sans `packageName` et cible alors `@obsidiane/bridge-sandbox` (app `apps/sandbox`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@obsidiane/meridiane",
-  "version": "2.0.5",
+  "version": "2.0.7",
   "description": "Générateur de librairie Angular et modèles TypeScript (OpenAPI) pour un bridge Symfony/API Platform + Mercure.",
   "repository": {
     "type": "git",
@@ -23,10 +23,10 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20.19"
   },
   "dependencies": {
-    "commander": "^14.0.2",
+    "commander": "^14.0.3",
     "handlebars": "^4.7.8",
     "tslib": "^2.3.0"
   }

package/templates/_lib_template/README.md

@@ -17,7 +17,7 @@ Le bridge est conçu pour être installé dans une application Angular. Les dép
 
 ## Compatibilité
 
-- Angular `@angular/*` `^20.1.0`
+- Angular `@angular/*` `^20.0.0 || ^21.0.0`
 - RxJS `^7.8.0`
 
 ## Démarrage rapide
@@ -60,7 +60,7 @@ export class AppModule {}
 `provideBridge({ ... })` accepte notamment :
 - `baseUrl` (requis) ;
 - `auth` (Bearer ou interceptor custom) ;
-- `mercure` (hubUrl + options SSE) ;
+- `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) ;
@@ -186,9 +186,22 @@ provideBridge({
 
 ### Concurrence
 
-Le bridge maintient une seule connexion SSE (une seule `EventSource`) et mutualise les topics :
-- regarder plusieurs fois la même ressource ne crée pas plusieurs connexions ;
-- un même topic est dédoublonné et géré par ref-count (unsubscribe effectif quand plus personne n’écoute).
+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$`.
+
+```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 ;
@@ -203,12 +216,68 @@ provideBridge({baseUrl: 'https://api.example.com', singleFlight: false});
 ```
 
 API :
-- `ResourceFacade<T>.watch$(iri | iri[])` / `unwatch(iri | iri[])`
-- `ResourceFacade<T>.watchSubResource$(iri | iri[], 'field.path')`
-- `BridgeFacade.watch$(iri | iri[])` / `unwatch(iri | iri[])`
+- `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.
 
+### Topic “multi-entités” (event-bus)
+
+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).
+
+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;
+  }
+});
+```
+
 ## Models TypeScript
 
 Les models générés (si présents) sont exportés au même niveau que le runtime :

package/templates/_lib_template/package.json

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