@obsidiane/meridiane 2.0.0 → 2.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@obsidiane/meridiane",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Générateur de librairie Angular et modèles TypeScript (OpenAPI) pour un bridge Symfony/API Platform + Mercure.",
   "repository": {
     "type": "git",

package/templates/_lib_template/README.md

@@ -0,0 +1,221 @@
+# __PACKAGE_NAME__
+
+Bridge Angular (runtime + models TypeScript) pour une API Platform (Hydra/JSON-LD), avec support Mercure/SSE optionnel.
+
+Le package expose une API Angular volontairement minimaliste :
+- `provideBridge()` pour configurer le bridge (HTTP + tokens + Mercure) ;
+- `FacadeFactory` / `ResourceFacade<T>` pour une API orientée ressource ;
+- `BridgeFacade` pour des appels ad-hoc.
+
+## Installation
+
+```bash
+npm i __PACKAGE_NAME__
+```
+
+Le bridge est conçu pour être installé dans une application Angular. Les dépendances Angular et RxJS sont des `peerDependencies`.
+
+## Compatibilité
+
+- Angular `@angular/*` `^20.1.0`
+- RxJS `^7.8.0`
+
+## Démarrage rapide
+
+Configurez le bridge au démarrage de l’application avec `provideBridge()` (requis).
+
+### Application standalone (recommandé)
+
+```ts
+// app.config.ts (ou main.ts)
+import {ApplicationConfig} from '@angular/core';
+import {provideBridge} from '__PACKAGE_NAME__';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideBridge({
+      baseUrl: 'https://api.example.com',
+      mercure: {hubUrl: 'https://api.example.com/.well-known/mercure'},
+    }),
+  ],
+};
+```
+
+### Application NgModule
+
+```ts
+import {NgModule} from '@angular/core';
+import {provideBridge} from '__PACKAGE_NAME__';
+
+@NgModule({
+  providers: [
+    provideBridge({baseUrl: 'https://api.example.com'}),
+  ],
+})
+export class AppModule {}
+```
+
+## Configuration
+
+`provideBridge({ ... })` accepte notamment :
+- `baseUrl` (requis) ;
+- `auth` (Bearer ou interceptor custom) ;
+- `mercure` (hubUrl + options SSE) ;
+- `defaults` (headers/timeout/retries) ;
+- `singleFlight` (déduplication “in-flight” des requêtes HTTP identiques `GET/HEAD/OPTIONS`) ;
+- `debug` (logs runtime) ;
+- `extraInterceptors` (interceptors Angular additionnels).
+
+### 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 aussi surcharger au cas par cas via `opts.withCredentials` sur les appels HTTP.
+
+```ts
+import {provideBridge} from '__PACKAGE_NAME__';
+
+provideBridge({
+  baseUrl: 'https://api.example.com',
+  mercure: {
+    hubUrl: 'https://api.example.com/.well-known/mercure',
+    init: {credentials: 'omit'},
+  },
+});
+```
+
+### Auth (Bearer)
+
+`auth` accepte :
+- une string (token Bearer),
+- `{ type: 'bearer', token }`,
+- `{ type: 'bearer', getToken }` (sync ou async),
+- ou un `HttpInterceptorFn` custom.
+
+```ts
+import {provideBridge} from '__PACKAGE_NAME__';
+
+provideBridge({
+  baseUrl: 'https://api.example.com',
+  auth: {type: 'bearer', getToken: () => localStorage.getItem('token') ?? undefined},
+});
+```
+
+### Defaults (headers / timeout / retries)
+
+```ts
+import {provideBridge} from '__PACKAGE_NAME__';
+
+provideBridge({
+  baseUrl: 'https://api.example.com',
+  defaults: {
+    headers: {'X-Requested-With': 'fetch'},
+    timeoutMs: 15_000,
+    retries: {count: 2, delayMs: 250, methods: ['GET']},
+  },
+});
+```
+
+### Debug
+
+```ts
+import {provideBridge} from '__PACKAGE_NAME__';
+
+provideBridge({baseUrl: 'https://api.example.com', debug: true});
+```
+
+## Appeler l’API
+
+### Style orienté ressource (`FacadeFactory` + `ResourceFacade<T>`)
+
+```ts
+import {inject} from '@angular/core';
+import {FacadeFactory, ResourceFacade, Item} from '__PACKAGE_NAME__';
+
+type Book = Item & {title?: string};
+
+export class BooksService {
+  private readonly factory = inject(FacadeFactory);
+  readonly books: ResourceFacade<Book> = this.factory.create<Book>({url: '/api/books'});
+}
+```
+
+Exemples :
+
+```ts
+// collection Hydra
+this.books.getCollection$({page: 1, itemsPerPage: 20, filters: {title: 'Dune'}});
+
+// item (souvent via @id)
+this.books.get$(book['@id']!);
+
+// write
+this.books.post$({title: 'Neuromancer'});
+this.books.patch$(book['@id']!, {title: 'Count Zero'});
+this.books.delete$(book['@id']!);
+```
+
+### Style ad-hoc (`BridgeFacade`)
+
+```ts
+import {inject} from '@angular/core';
+import {BridgeFacade} from '__PACKAGE_NAME__';
+
+export class HealthService {
+  private readonly bridge = inject(BridgeFacade);
+  getHealth$() {
+    return this.bridge.get$<{status: string}>('/health');
+  }
+}
+```
+
+## Realtime (Mercure/SSE)
+
+Le realtime est inactif tant que `mercure.hubUrl` n’est pas fourni à `provideBridge()`.
+
+```ts
+provideBridge({
+  baseUrl: 'https://api.example.com',
+  mercure: {hubUrl: 'https://api.example.com/.well-known/mercure', topicMode: 'url'},
+});
+```
+
+### 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).
+
+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 ;
+- les méthodes avec body (`POST`/`PUT`/`PATCH`/`DELETE`) ne sont pas dédupliquées.
+
+Ce n’est pas un cache : une fois la requête terminée, un nouvel appel identique relance un nouvel appel réseau.
+
+Pour désactiver :
+
+```ts
+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[])`
+
+Note SSR : la connexion SSE ne s’ouvre que dans le navigateur.
+
+## Models TypeScript
+
+Les models générés (si présents) sont exportés au même niveau que le runtime :
+
+```ts
+import type {Item} from '__PACKAGE_NAME__';
+// import type {Book} from '__PACKAGE_NAME__';
+```
+
+En JSON-LD (`application/ld+json`), l’IRI est typiquement dans `model['@id']`.

package/templates/_lib_template/ng-package.json

@@ -1,6 +1,9 @@
 {
   "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
   "dest": "../../dist/__LIB_NAME__",
+  "assets": [
+    "README.md"
+  ],
   "lib": {
     "entryFile": "src/public-api.ts"
   }

package/templates/_lib_template/src/lib/interceptors/singleflight.interceptor.ts

@@ -0,0 +1,55 @@
+import {HttpEvent, HttpInterceptorFn, HttpRequest} from '@angular/common/http';
+import {finalize, Observable, shareReplay} from 'rxjs';
+
+export type SingleFlightMode = 'off' | 'safe';
+
+const DEFAULT_MODE: SingleFlightMode = 'safe';
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+
+export function createSingleFlightInterceptor(mode: SingleFlightMode = DEFAULT_MODE): HttpInterceptorFn {
+  const inflight = new Map<string, Observable<HttpEvent<unknown>>>();
+
+  return (req, next) => {
+    if (mode === 'off') {
+      return next(req);
+    }
+
+    const method = req.method.toUpperCase();
+    if (!SAFE_METHODS.has(method)) {
+      return next(req);
+    }
+    if (req.reportProgress === true) {
+      return next(req);
+    }
+
+    const key = computeKey(req);
+    const existing = inflight.get(key);
+    if (existing) {
+      return existing;
+    }
+
+    const shared$ = next(req).pipe(
+      finalize(() => inflight.delete(key)),
+      shareReplay({bufferSize: 1, refCount: true})
+    );
+
+    inflight.set(key, shared$);
+    return shared$;
+  };
+}
+
+function computeKey(req: HttpRequest<unknown>): string {
+  const auth = req.headers.get('Authorization') ?? '';
+  const accept = req.headers.get('Accept') ?? '';
+  const contentType = req.headers.get('Content-Type') ?? '';
+  const creds = req.withCredentials ? '1' : '0';
+  return [
+    req.method.toUpperCase(),
+    req.urlWithParams,
+    `rt=${req.responseType}`,
+    `wc=${creds}`,
+    `a=${auth}`,
+    `acc=${accept}`,
+    `ct=${contentType}`,
+  ].join('::');
+}

package/templates/_lib_template/src/lib/provide-bridge.ts

@@ -13,6 +13,7 @@ import {contentTypeInterceptor} from './interceptors/content-type.interceptor';
 import {bridgeDefaultsInterceptor} from './interceptors/bridge-defaults.interceptor';
 import {bridgeDebugInterceptor} from './interceptors/bridge-debug.interceptor';
 import {from, switchMap} from 'rxjs';
+import {createSingleFlightInterceptor} from './interceptors/singleflight.interceptor';
 
 export type BridgeAuth =
   | string
@@ -37,6 +38,13 @@ export interface BridgeOptions {
   mercure?: BridgeMercureOptions;
   /** Default HTTP behaviour (headers, timeout, retries). */
   defaults?: BridgeDefaults;
+  /**
+   * De-duplicates in-flight HTTP requests.
+   *
+   * - `true` (default): single-flight for safe methods (`GET/HEAD/OPTIONS`)
+   * - `false`: disabled (each call triggers a new request)
+   */
+  singleFlight?: boolean;
   /** Enables debug logging via the debug interceptor and console logger. */
   debug?: boolean;
   /** Extra `HttpInterceptorFn` applied after bridge interceptors. */
@@ -50,6 +58,7 @@ export function provideBridge(opts: BridgeOptions): EnvironmentProviders {
     auth,
     mercure,
     defaults,
+    singleFlight = true,
     debug = false,
     extraInterceptors = [],
   } = opts;
@@ -69,6 +78,7 @@ export function provideBridge(opts: BridgeOptions): EnvironmentProviders {
     contentTypeInterceptor,
     bridgeDefaultsInterceptor,
     ...createAuthInterceptors(auth),
+    ...(singleFlight ? [createSingleFlightInterceptor('safe')] : [createSingleFlightInterceptor('off')]),
     ...(debug ? [bridgeDebugInterceptor] : []),
     ...extraInterceptors,
   ];

package/tools/core/generate.js

@@ -1,12 +1,12 @@
 import fs from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import {existsSync} from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import {fileURLToPath} from 'node:url';
 
-import { readJson, writeJsonIfChanged } from './json.js';
-import { renderTemplateToFile } from '../generator/models/handlebars.js';
-import { ensureCleanDir } from '../generator/models/utils.js';
-import { buildModelsFromOpenAPI } from '../generator/models/openapi-to-models.js';
+import {readJson, writeJsonIfChanged} from './json.js';
+import {renderTemplateToFile} from '../generator/models/handlebars.js';
+import {ensureCleanDir} from '../generator/models/utils.js';
+import {buildModelsFromOpenAPI} from '../generator/models/openapi-to-models.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -14,7 +14,7 @@ const __dirname = path.dirname(__filename);
 const pkgRoot = path.resolve(__dirname, '../..'); // packages/meridiane
 
 async function replacePlaceholdersInDir(dir, placeholders) {
-  const entries = await fs.readdir(dir, { withFileTypes: true });
+  const entries = await fs.readdir(dir, {withFileTypes: true});
   for (const entry of entries) {
     const fullPath = path.join(dir, entry.name);
     if (entry.isDirectory()) {
@@ -29,17 +29,25 @@ async function replacePlaceholdersInDir(dir, placeholders) {
   }
 }
 
-async function generateLibrary({ cwd, libName, packageName, version, debug }) {
+async function generateLibrary({cwd, libName, packageName, version, debug}) {
   const tplDir = path.resolve(pkgRoot, 'templates/_lib_template');
   const targetDir = path.resolve(cwd, 'projects', libName);
 
-  if (debug) console.log('[meridiane] generate lib', { libName, packageName, version, targetDir: path.relative(cwd, targetDir) });
+  if (debug) console.log('[meridiane] generate lib', {
+    libName,
+    packageName,
+    version,
+    targetDir: path.relative(cwd, targetDir)
+  });
 
-  await fs.rm(targetDir, { recursive: true, force: true });
-  await fs.mkdir(targetDir, { recursive: true });
-  await fs.cp(tplDir, targetDir, { recursive: true });
+  await fs.rm(targetDir, {recursive: true, force: true});
+  await fs.mkdir(targetDir, {recursive: true});
+  await fs.cp(tplDir, targetDir, {recursive: true});
 
-  await replacePlaceholdersInDir(targetDir, { '__LIB_NAME__': libName });
+  await replacePlaceholdersInDir(targetDir, {
+    '__LIB_NAME__': libName,
+    '__PACKAGE_NAME__': packageName,
+  });
 
   const libPackageJsonPath = path.join(targetDir, 'package.json');
   if (existsSync(libPackageJsonPath)) {
@@ -52,7 +60,7 @@ async function generateLibrary({ cwd, libName, packageName, version, debug }) {
   // angular.json / workspace patching is intentionally not done here (Meridiane is standalone).
 }
 
-async function generateModels({ cwd, libName, spec, requiredMode, formats, include, exclude, debug }) {
+async function generateModels({cwd, libName, spec, requiredMode, formats, include, exclude, debug}) {
   const outDir = path.resolve(cwd, 'projects', libName, 'src', 'models');
   const templatesDir = path.resolve(pkgRoot, 'tools', 'generator', 'models', 'templates');
 
@@ -68,7 +76,7 @@ async function generateModels({ cwd, libName, spec, requiredMode, formats, inclu
   await ensureCleanDir(outDir);
 
   // Write models + index.ts.
-  const { models } = buildModelsFromOpenAPI(spec, {
+  const {models} = buildModelsFromOpenAPI(spec, {
     requiredMode,
     formats: Array.isArray(formats) ? formats : [],
     includeSchemaNames: include,
@@ -92,7 +100,7 @@ async function generateModels({ cwd, libName, spec, requiredMode, formats, inclu
   await renderTemplateToFile({
     templatePath: path.join(templatesDir, 'index.hbs'),
     outPath: path.join(outDir, 'index.ts'),
-    ctx: { models: models.map((m) => ({ name: m.name })) },
+    ctx: {models: models.map((m) => ({name: m.name}))},
   });
 
   if (debug) console.log(`[meridiane] ${models.length} model(s) generated`);
@@ -134,7 +142,7 @@ export async function generateBridgeWorkspace(params) {
   } = params;
 
   log?.step?.(`génération de la librairie (projects/${libName})`);
-  await generateLibrary({ cwd, libName, packageName, version, debug });
+  await generateLibrary({cwd, libName, packageName, version, debug});
 
   // If a dist root is provided, force ng-packagr output to that directory.
   if (distRoot) {
@@ -144,7 +152,7 @@ export async function generateBridgeWorkspace(params) {
     const projectDir = path.dirname(ngPackagePath);
     ngPkg.dest = path.relative(projectDir, desiredDestAbs).split(path.sep).join('/');
     await writeJsonIfChanged(ngPackagePath, ngPkg);
-    log?.debug?.('ng-package.json dest overridden', { dest: ngPkg.dest });
+    log?.debug?.('ng-package.json dest overridden', {dest: ngPkg.dest});
   }
 
   if (noModels) {
@@ -155,6 +163,6 @@ export async function generateBridgeWorkspace(params) {
 
   if (!spec) throw new Error('Internal error: spec is required when noModels=false');
   log?.step?.('génération des models (OpenAPI)');
-  await generateModels({ cwd, libName, spec, requiredMode, formats, include, exclude, debug });
+  await generateModels({cwd, libName, spec, requiredMode, formats, include, exclude, debug});
   log?.success?.('génération terminée');
 }