@esfaenza/dpe-builder 20.3.3 → 20.3.6

package/index.d.ts

@@ -657,6 +657,17 @@ interface DpeFieldMappingInfo {
 interface DpeCompiledWriteback {
     writebackName: string;
     sequence: number;
+    /**
+     * L'intento di scrittura di questo writeback: operazione, tabella, chiave di corrispondenza,
+     * gruppo atomico, target. **Mai assente** (`contracts.md` §5), ed e' la **stessa istanza** che
+     * compare in `DpeCompileResult.writebackSequence` (ADR 0018).
+     *
+     * Sta qui e non duplicato campo per campo su questo tipo: senza di esso il client non ha modo di
+     * sapere *cosa* fa uno statement — mostrerebbe l'SQL di un `Upsert` e di una `Delete` allo stesso
+     * modo — e l'unica alternativa sarebbe incrociare `writebackSequence` per nome, cioe' ricostruire
+     * a mano un collegamento che il backend manda gia' fatto.
+     */
+    step: DpeWritebackStep;
     statement: SqlStatement;
     resultColumns?: DpeColumnInfo[];
     /** Vedi {@link DpeFieldMappingInfo}: forma provvisoria. */
@@ -989,6 +1000,20 @@ declare class HttpDpeBuilderApi extends DpeBuilderApi {
     protected url(path: string): string;
     /** Codifica di un segmento variabile. Un nome di definizione puo' contenere `/`, spazi, `&`. */
     protected segment(value: string): string;
+    /**
+     * La chiave che finisce in un segmento di rotta, **verificata prima di partire**.
+     *
+     * Perche' esiste: `encodeURIComponent(undefined)` vale `'undefined'`, e senza questo controllo un
+     * nome mancante non produceva nessun errore — produceva `PUT /definitions/undefined`, cioe' una
+     * richiesta sensata per il trasporto e priva di senso per il dominio. La sbaglia il backend
+     * (`404`, o peggio: sovrascrive una definizione che si chiama davvero cosi'), e chi guarda la rete
+     * vede una chiave inventata dal client senza sapere da dove arrivi.
+     *
+     * Rifiuta **senza emettere la richiesta**: una chiave assente non si ritenta e non riguarda il
+     * backend. La categoria e' `Backend` e non `MissingService` — il comando c'e' e non va disabilitato
+     * — ne' `Transport`, che significherebbe «ritenta».
+     */
+    protected requireKey(value: string | null | undefined, primitive: string, what: string): string;
     /**
      * Cio' che avvolge **ogni** chiamata, e l'unico posto in cui si decide se una chiamata parte.
      *
@@ -1034,6 +1059,31 @@ declare class HttpDpeBuilderApi extends DpeBuilderApi {
     /** L'**unica** rotta con involucro: il corpo porta anche i valori dei parametri (§7-bis). */
     compilePreview(definition: DpeDefinition, parameterValues?: DpeParameterValue[]): Observable<DpeCompileResult>;
     load(name: string): Observable<DpeDefinition>;
+    /**
+     * La risposta di `load` **e' una definizione**, e qui si verifica invece di sperarlo.
+     *
+     * Costa quattro righe e trasforma il difetto peggiore di questo contratto in un errore immediato
+     * che nomina la causa. Senza, una risposta della forma sbagliata non produce nessun errore:
+     * produce un editor con il canvas vuoto e un `name` `undefined`, che si manifesta molto piu' tardi
+     * come un salvataggio verso una chiave inventata. I tre modi in cui succede davvero:
+     *
+     * - il backend restituisce **l'involucro della lettura** (`{ definition, diagnostics, hasErrors }`)
+     *   invece del documento: e' l'esito di `IDpeService.Deserialize`, ed e' un errore facile da fare
+     *   scrivendo `Ok(read)` al posto di `Ok(documento)`;
+     * - la risposta e' in **PascalCase**: `Name` non e' `name`, e in TypeScript non e' un errore;
+     * - la rotta risponde un **sommario** (`DpeDefinitionSummary`) invece della definizione: si
+     *   somigliano, e il sommario ha `name` ma non `formatVersion` ne' i nodi.
+     *
+     * Si controllano le due proprieta' **obbligatorie** del documento e nient'altro: una definizione
+     * puo' legittimamente non avere nessun nodo, e verificare di piu' vorrebbe dire validare, che e'
+     * del backend.
+     */
+    protected requireDefinition(payload: unknown): DpeDefinition;
+    /**
+     * Il nome viene dal **documento** e non da un parametro: e' la chiave, e la rotta e'
+     * `PUT /definitions/{definition.name}`. Se manca, la chiamata si rifiuta qui — un salvataggio
+     * senza chiave non e' un salvataggio, e una definizione nuova si crea con `createDefinition`.
+     */
     save(definition: DpeDefinition): Observable<void>;
     /**
      * La dichiarazione dell'ambiente (ADR 0017). Questo client la implementa perche' conosce
@@ -1514,8 +1564,16 @@ declare class DpeDocumentStore {
     select(nodeName: string | undefined): void;
     /** Selezione multipla (riquadro, `Ctrl+A`): la lista che arriva dal gesto, senza duplicati. */
     selectMany(nodeNames: readonly string[]): void;
-    /** Proprieta' della radice: etichetta, descrizione, dialetto, parametri. */
-    patchDefinition(patch: Partial<DpeDefinition>): void;
+    /**
+     * Proprieta' della radice: etichetta, descrizione, dialetto, parametri.
+     *
+     * **`name` e `formatVersion` non sono nell'insieme**, e il tipo lo impedisce invece di dirlo in un
+     * commento. `name` e' la chiave del catalogo: rinominare e' creare-e-cancellare (ADR 0019), non
+     * una modifica del documento — e `Partial<DpeDefinition>` permetteva `{ name: undefined }`, che
+     * lasciava nel documento una chiave senza valore. Da li' il salvataggio partiva verso
+     * `PUT /definitions/undefined`. `formatVersion` e' del formato, non dell'autore.
+     */
+    patchDefinition(patch: Partial<Omit<DpeDefinition, 'name' | 'formatVersion'>>): void;
     addNode<K extends DpeNodeCollectionName>(collection: K, node: DpeNodeCollectionMap[K]): void;
     updateNode<K extends DpeNodeCollectionName>(collection: K, nodeName: string, patch: Partial<DpeNodeCollectionMap[K]>): void;
     /**
@@ -1878,6 +1936,31 @@ declare class DpeBuilderComponent {
      * (ADR 0006), che e' dell'host. Assente `getEnvironment`, non c'e' niente da confrontare.
      */
     protected readonly dialectMismatch: Signal<SqlDialectKind | undefined>;
+    /**
+     * Il documento porta una chiave utilizzabile. Il nome **e'** la chiave del catalogo, e la rotta di
+     * aggiornamento e' `PUT /definitions/{name}`: senza nome non c'e' niente da aggiornare, e una
+     * definizione nuova si crea dal catalogo (ADR 0019), non da qui.
+     *
+     * Sta qui e non solo nel client per la ragione che questo progetto applica alle primitive
+     * assenti: un comando disabilitato che dice il motivo e' meglio di un comando attivo che fallisce
+     * alla pressione. Il client rifiuta comunque — e' lui che compone l'URL, e un ospite che chiami
+     * `save()` per vie proprie deve trovare la stessa risposta.
+     */
+    protected readonly hasKey: Signal<boolean>;
+    /**
+     * Il documento ricevuto **non e' una definizione**, detto subito e a schermo.
+     *
+     * L'unico ingresso e' l'input `definition`, e finora l'editor accettava qualunque oggetto: con un
+     * documento della forma sbagliata mostrava un canvas vuoto — che sembra una definizione senza
+     * nodi, cioe' uno stato legittimo — e il difetto ricompariva molto piu' tardi come un salvataggio
+     * verso una chiave che il client doveva inventare. Le tre forme che arrivano davvero al posto del
+     * documento sono l'involucro di lettura (`{ definition, diagnostics }`), il **sommario** del
+     * catalogo (ha `name` ma non `formatVersion` ne' i nodi) e una risposta in PascalCase.
+     *
+     * Si controllano le due proprieta' obbligatorie e nient'altro: una definizione senza nodi e'
+     * legittima, e verificare di piu' sarebbe validare — che e' del backend (I6).
+     */
+    protected readonly documentProblem: Signal<string | undefined>;
     protected readonly canSave: Signal<boolean>;
     protected readonly nodeCount: Signal<number>;
     constructor();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esfaenza/dpe-builder",
-  "version": "20.3.3",
+  "version": "20.3.6",
   "peerDependencies": {
     "@angular/cdk": "^20.2.14",
     "@angular/common": "^20.3.25",