@obsidiane/meridiane 1.0.1 → 2.0.1

package/README.md

@@ -21,18 +21,21 @@ npm i -g @obsidiane/meridiane
 ```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> [--preset[=native|all]] [--include <substr>]... [--exclude <substr>]... [--no-models] [--debug]
+npx meridiane dev <packageName> --spec <url|file> [--formats <mimeTypes>]... [--include <substr>]... [--exclude <substr>]... [--no-models] [--debug]
 
 # CI/CD: génère + build Angular + npm pack (artefact prêt à publier)
-npx meridiane build <packageName> --version <semver> --spec <url|file> [--preset[=native|all]] [--include <substr>]... [--exclude <substr>]... [--no-models] [--debug]
+npx meridiane build <packageName> --version <semver> --spec <url|file> [--formats <mimeTypes>]... [--include <substr>]... [--exclude <substr>]... [--no-models] [--debug]
 ```
 
 Options :
 - `--debug` : active des logs supplémentaires (CLI).
+- `--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 `--preset=native` pour un mode “contract-driven” (LD+JSON) :
-  - modèles générés uniquement s’ils sont utilisés par les endpoints
+- 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`)
@@ -45,7 +48,7 @@ Note (repo Meridiane) :
 ## Exemple CI (générer + build + publish)
 
 ```bash
-npx -y @obsidiane/meridiane@0.1.0 build @acme/backend-bridge --version 0.1.0 --spec https://staging.example/api/docs.json --preset=native
+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
 ```
 

package/cli.js

@@ -8,16 +8,7 @@ import { createLogger } from './tools/core/logger.js';
 
 const program = new Command();
 
-program
-  .name('meridiane')
-  .description('Generate an Angular bridge + models from an API Platform OpenAPI spec.')
-  .showHelpAfterError()
-  .showSuggestionAfterError();
-
-function presetParser(value, previous) {
-  if (value === undefined && previous === undefined) return true; // `--preset` (no value) => native
-  return value ?? previous;
-}
+program.name('meridiane').description('Generate an Angular bridge + models from an API Platform OpenAPI spec.').showHelpAfterError().showSuggestionAfterError();
 
 function collect(value, previous = []) {
   return [...previous, value];
@@ -26,7 +17,12 @@ function collect(value, previous = []) {
 function commonOptions(cmd) {
   return cmd
     .option('--spec <urlOrFile>', 'OpenAPI spec source (URL or local JSON file)')
-    .option('--preset [mode]', 'Preset: native|all (default: all; `--preset` alone => native)', presetParser)
+    .option(
+      '--formats <mimeTypes>',
+      'Generate only selected media types (repeatable, supports commas). Enables contract-driven mode from paths.',
+      collect,
+      []
+    )
     .option('--include <substr>', 'Include schema names containing substring (repeatable, supports commas)', collect, [])
     .option('--exclude <substr>', 'Exclude schema names containing substring (repeatable, supports commas)', collect, [])
     .option('--no-models', 'Skip models generation (then --spec is not required)')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@obsidiane/meridiane",
-  "version": "1.0.1",
+  "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/build.js

@@ -4,7 +4,7 @@ import { spawn } from 'node:child_process';
 import path from 'node:path';
 
 import { deriveLibName } from './core/lib-name.js';
-import { normalizePreset, splitListArgs } from './core/paths.js';
+import { splitListArgs } from './core/paths.js';
 import { readOpenApiSpec } from './core/spec.js';
 import { createLogger } from './core/logger.js';
 import { generateBridgeWorkspace } from './core/generate.js';
@@ -30,20 +30,21 @@ export async function runBuild(packageName, opts) {
   if (!version) throw new Error('Missing --version');
 
   const noModels = opts.models === false;
-  const preset = normalizePreset(opts.preset);
+  const formats = splitListArgs(opts.formats);
   const include = splitListArgs(opts.include);
   const exclude = splitListArgs(opts.exclude);
 
   const libName = deriveLibName(packageName);
   const requiredMode = 'spec';
+  const effectiveFormats = formats.length > 0 ? formats : ['application/ld+json'];
 
-  // Standalone mode (native): works from any repo (backend pipeline or otherwise).
+  // Standalone mode: works from any repo (backend pipeline or otherwise).
   log.title('build — standalone');
   log.info(`repo: ${cwd}`);
   log.info(`package: ${packageName}@${version}`);
   log.info(`lib: ${libName}`);
   if (noModels) log.info('models: désactivés (--no-models)');
-  else log.info(`spec: ${opts.spec} | preset: ${preset}`);
+  else log.info(`spec: ${opts.spec} | formats: ${effectiveFormats.join(', ')} | nullableMode: ${requiredMode}`);
 
   const { workspaceRoot, distRoot, npmCacheDir, requireFromWs } = await ensureStandaloneWorkspace({ repoRoot: cwd, log });
   log.info(`workspace: ${workspaceRoot}`);
@@ -65,7 +66,7 @@ export async function runBuild(packageName, opts) {
     noModels,
     spec,
     requiredMode,
-    preset,
+    formats: effectiveFormats,
     include,
     exclude,
     debug,

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,18 +60,25 @@ 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, preset, 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');
 
-  if (debug) console.log('[meridiane] generate models', { outDir: path.relative(cwd, outDir), requiredMode, preset, includeCount: include.length, excludeCount: exclude.length });
+  if (debug)
+    console.log('[meridiane] generate models', {
+      outDir: path.relative(cwd, outDir),
+      requiredMode,
+      formats: Array.isArray(formats) ? formats : [],
+      includeCount: include.length,
+      excludeCount: exclude.length,
+    });
 
   await ensureCleanDir(outDir);
 
   // Write models + index.ts.
-  const { models } = buildModelsFromOpenAPI(spec, {
+  const {models} = buildModelsFromOpenAPI(spec, {
     requiredMode,
-    preset,
+    formats: Array.isArray(formats) ? formats : [],
     includeSchemaNames: include,
     excludeSchemaNames: exclude,
   });
@@ -77,6 +92,7 @@ async function generateModels({ cwd, libName, spec, requiredMode, preset, includ
         props: m.props,
         imports: m.imports,
         extendsTypes: m.extendsTypes || [],
+        extendsItem: m.extendsItem === true,
       },
     });
   }
@@ -84,7 +100,7 @@ async function generateModels({ cwd, libName, spec, requiredMode, preset, includ
   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`);
@@ -98,8 +114,8 @@ async function generateModels({ cwd, libName, spec, requiredMode, preset, includ
  *   version: string,
  *   noModels: boolean,
  *   spec?: any,
- *   requiredMode: 'all-optional'|'spec',
- *   preset: 'all'|'native',
+ *   requiredMode: 'all'|'spec',
+ *   formats?: string[],
  *   include: string[],
  *   exclude: string[],
  *   debug: boolean,
@@ -117,7 +133,7 @@ export async function generateBridgeWorkspace(params) {
     noModels,
     spec,
     requiredMode,
-    preset,
+    formats,
     include,
     exclude,
     debug,
@@ -126,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) {
@@ -136,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) {
@@ -147,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, preset, include, exclude, debug });
+  await generateModels({cwd, libName, spec, requiredMode, formats, include, exclude, debug});
   log?.success?.('génération terminée');
 }

package/tools/core/paths.js

@@ -1,10 +1,3 @@
-export function normalizePreset(presetOption) {
-  if (presetOption === undefined) return 'all';
-  if (presetOption === true) return 'native';
-  if (presetOption === 'native' || presetOption === 'all') return presetOption;
-  throw new Error(`Invalid --preset value: ${presetOption} (expected: native|all)`);
-}
-
 export function splitListArgs(values) {
   const out = [];
   for (const v of Array.isArray(values) ? values : []) {

package/tools/dev.js

@@ -5,7 +5,7 @@ import path from 'node:path';
 import { spawn } from 'node:child_process';
 
 import { deriveLibName } from './core/lib-name.js';
-import { normalizePreset, splitListArgs } from './core/paths.js';
+import { splitListArgs } from './core/paths.js';
 import { readOpenApiSpec } from './core/spec.js';
 import { createLogger } from './core/logger.js';
 import { generateBridgeWorkspace } from './core/generate.js';
@@ -139,12 +139,13 @@ export async function runDev(packageName, opts) {
   const libName = deriveLibName(effectivePackageName);
 
   const noModels = opts.models === false;
-  const preset = normalizePreset(useSandboxDefaults ? (opts.preset ?? 'native') : opts.preset);
+  const formats = splitListArgs(opts.formats);
   const include = splitListArgs(opts.include);
   const exclude = splitListArgs(opts.exclude);
 
   const version = '0.0.0-dev';
-  const requiredMode = 'all-optional';
+  const requiredMode = 'all';
+  const effectiveFormats = formats.length > 0 ? formats : ['application/ld+json'];
   const specSource = useSandboxDefaults ? (opts.spec ?? 'http://localhost:8000/api/docs.json') : opts.spec;
 
   log.title('dev — build standalone + install local');
@@ -153,7 +154,7 @@ export async function runDev(packageName, opts) {
   log.info(`lib: ${libName}`);
   if (useSandboxDefaults) log.info('defaults sandbox appliqués');
   if (noModels) log.info('models: désactivés (--no-models)');
-  else log.info(`spec: ${specSource} | preset: ${preset}`);
+  else log.info(`spec: ${specSource} | formats: ${effectiveFormats.join(', ')} | nullableMode: ${requiredMode}`);
 
   const { workspaceRoot, distRoot, npmCacheDir, requireFromWs } = await ensureStandaloneWorkspace({ repoRoot: appRoot, log });
   log.info(`workspace: ${workspaceRoot}`);
@@ -175,7 +176,7 @@ export async function runDev(packageName, opts) {
     noModels,
     spec,
     requiredMode,
-    preset,
+    formats: effectiveFormats,
     include,
     exclude,
     debug,