@obsidiane/meridiane

@obsidiane/meridiane

CLI pour générer un bridge Angular (runtime + models TypeScript) depuis une spec OpenAPI (API Platform + Mercure).

Documentation complète du repo : docs/guide-bridge.md.

Installation

npm i -D @obsidiane/meridiane

Commandes

meridiane generate <packageName>

Génère uniquement les sources du bridge dans le workspace courant.

npx meridiane generate @acme/backend-bridge --spec ./openapi.json

Sortie par défaut : projects/<libName>/ (modifiable via --out).

meridiane dev [packageName]

Génération + build standalone + npm pack + installation locale dans node_modules.

npx meridiane dev @acme/backend-bridge --spec http://localhost:8000/api/docs.json

Sorties :

• dist/<libName>/ + dist/<libName>/*.tgz
• node_modules/<packageName>/

meridiane build <packageName>

Génération + build standalone + npm pack (artefact publiable).

npx meridiane build @acme/backend-bridge --version 1.2.3 --spec https://staging.example/api/docs.json

Sorties :

• dist/<libName>/
• dist/<libName>/*.tgz

Options

• --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

• fallback automatique .../api/docs.json -> .../api/docs.jsonopenapi si nécessaire
• mode contract-driven : uniquement les schémas atteignables via paths et webhooks 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

Couverture des schémas

Le compilateur suit les types d’OpenAPI 3.0 et le dialecte JSON Schema 2020-12 d’OpenAPI 3.1 :

• primitives, unions de type, objets, propriétés requises, dictionnaires et schémas booléens ;
• tableaux homogènes, tuples prefixItems, tuples historiques et bornes de longueur des tuples ;
• enum et const, y compris les valeurs JSON structurées ;
• allOf, oneOf, anyOf, nullable et références locales vers components.schemas ou $defs ;
• schémas racine objets sous forme d’interfaces et autres schémas sous forme d’aliases TypeScript ;
• contrats atteignables depuis les bodies, paramètres, en-têtes, callbacks et webhooks.

Les règles de validation sans équivalent structurel TypeScript (pattern, bornes numériques, uniqueItems, contains, not, conditions, fermeture exacte des propriétés, etc.) restent à la charge de la validation runtime. Les références externes doivent être préalablement regroupées dans le document OpenAPI fourni à Meridiane.

Spécifique à ce repo

Dans ce monorepo, meridiane dev peut être exécuté sans packageName et cible alors @obsidiane/bridge-sandbox (app playground/angular-app).