@obsidiane/meridiane 2.0.4 → 2.0.6

package/README.md

@@ -1,8 +1,8 @@
 # @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.
+CLI pour générer un bridge Angular (API Platform + Mercure) depuis une spec OpenAPI.
 
-Documentation détaillée (repo) : `docs/index.md`.
+Documentation complète (repo) : `docs/guide-bridge.md`.
 
 ## Installation
 
@@ -16,54 +16,58 @@ Ou en global :
 npm i -g @obsidiane/meridiane
 ```
 
-## Usage
+## Commandes
+
+### `meridiane generate <packageName>`
+
+Génère uniquement les fichiers du bridge dans le workspace courant (pas de build, pas de `npm pack`).
 
 ```bash
-# Dev: génère le bridge (+ models par défaut)
-# (build standalone + install local dans node_modules)
-npx meridiane dev <packageName> --spec <url|file> [--formats <mimeTypes>]... [--include <substr>]... [--exclude <substr>]... [--no-models] [--debug]
+npx meridiane generate @acme/backend-bridge --spec ./openapi.json
+```
 
-# Monorepo: génère uniquement les fichiers (pas de npm pack)
-npx meridiane generate <packageName> --spec <url|file> [--formats <mimeTypes>]... [--include <substr>]... [--exclude <substr>]... [--no-models] [--out <dir>] [--debug]
+Sortie par défaut : `projects/<libName>/` (modifiable via `--out`).
 
-# CI/CD: génère + build Angular + npm pack (artefact prêt à publier)
-npx meridiane build <packageName> [--version <semver>] --spec <url|file> [--formats <mimeTypes>]... [--include <substr>]... [--exclude <substr>]... [--no-models] [--debug]
+### `meridiane dev [packageName]`
+
+Build standalone + installation locale dans `node_modules`.
+
+```bash
+npx meridiane dev @acme/backend-bridge --spec http://localhost:8000/api/docs.json
 ```
 
-Options :
-- `--debug` : active des logs supplémentaires (CLI).
-- `--version` : pour `build` et `generate` ; par défaut `0.0.0` si omis (déconseillé pour publier).
-- `--out` : uniquement pour `generate` ; répertoire de sortie (défaut `projects/<libName>`).
-- `--formats` : peut être répété ou fourni en liste séparée par virgules :
-  - `--formats application/ld+json`
-  - `--formats application/ld+json,application/json`
-
-Bonnes pratiques :
-- utiliser `--formats application/ld+json` (ou plusieurs formats) pour un mode “contract-driven” :
-  - modèles générés uniquement s’ils sont utilisés par les endpoints (pour ces formats)
-  - groups conservés
-  - pas de modèles `*.jsonMergePatch` (PATCH = `Partial<...>`)
-  - noms normalisés (pas de suffixe `.jsonld`)
-- utiliser `--no-models` si vous voulez uniquement le runtime (pas besoin de `--spec`)
-- le `README.md` du projet (si présent à la racine) est ajouté à la fin du README du bridge
-- laisser le registry à la CI (`.npmrc`, variables d’environnement, `npm publish --registry …`)
-
-Note (repo Meridiane) :
-- dans le repo Meridiane, `meridiane dev` peut être exécutée sans `packageName` et se préconfigure pour `apps/sandbox` (`@obsidiane/bridge-sandbox`).
-
-## Exemple CI (générer + build + publish)
+Sorties :
+- `dist/<libName>/` + `dist/<libName>/*.tgz`
+- `node_modules/<packageName>/`
+
+### `meridiane build <packageName>`
+
+Build standalone + `npm pack` (artefact publiable).
 
 ```bash
-npx -y @obsidiane/meridiane@0.1.0 build @acme/backend-bridge --version 0.1.0 --spec https://staging.example/api/docs.json --formats application/ld+json
-npm publish dist/backend-bridge
+npx meridiane build @acme/backend-bridge --version 0.1.0 --spec https://staging.example/api/docs.json
 ```
 
-Note : Meridiane installe le toolchain (`ng-packagr`, `@angular/*`, …) dans `dist/.meridiane-workspace` si nécessaire.
+Sorties :
+- `dist/<libName>/`
+- `dist/<libName>/*.tgz`
+
+## 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.
+
+## 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.
 
-## Structure interne (mainteneurs)
+## Note (repo Meridiane)
 
-- `tools/app/` : orchestration des commandes (use-cases).
-- `tools/domain/` : logique pure (options, naming).
-- `tools/infra/` : I/O (spec, workspace, exec, logs) + génération.
-- `tools/generator/` : génération des modèles TypeScript.
-- `templates/_lib_template/` : runtime Angular du bridge.
+Dans ce repo, `meridiane dev` peut être exécutée sans `packageName` et cible l’app sandbox (`apps/sandbox`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@obsidiane/meridiane",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "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": {