@obsidiane/meridiane 2.0.0 → 2.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@obsidiane/meridiane",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "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,194 @@
+# __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 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()`.
+
+### 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
+
+### 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'},
+});
+```
+
+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/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');
 }