Skip to main content

Estendere la configurazione

Il modulo di default non contiene nessuna configurazione. E' necessario estenderlo per aggiungere nuove opzioni. L'estensione viene implementata:

  • A livello applicativo, per le configurazioni che sono caso-specifiche. In questo caso, i metodi vengono chiamati direttamente nel progetto finale, i.e. arkeion.
  • A livello di libreria, nel caso di pacchetti di @favojs che espongono una configurazione aggiuntiva, come @favojs/logger che richiede un path in cui salvare i log.

In questo modo si ha un unico file di configurazione per più pacchetti, dato che la configurazione è centralizzata.

Procedura#

Per estendere la configurazione, sono necessari i seguenti passaggi:

  1. Definire il validatore per la configurazione (basato su @favojs/validation)
  2. Estendere l'interfaccia di configurazione di IAppConfig, con il type ottenuto dal validatore.
  3. Registrare il validatore su AppConfig
Struttura dei File

Per le librerire @favojs, definire il validatore e l'estensione dell'intefaccia in un unico file posizionato in src/config/<pkg>Config.ts, ad esempio src/config/LoggerConfig.ts.

Definizione del validatore#

E' necessario definire un validatore per la configurazione, con il duplice scopo di:

  1. Ottenere i type, per avere a disposizione l'IntelliSense e la validazione statica di TypeScript nell'uso delle variabili di configurazione
  2. Assicurarsi che gli utenti delle librerie/software inseriscano i valori corretti.

Il validatore utilizzato è Yup, con le estensioni fornite da @favojs/validation.

export const customConfigValidator = yup
.object({
example: yup.string().required(),
second: yup.string().default("second value"),
})
.required()
.noUnknown();
// La registrazione del tipo è necessaria per l'estensione dell'interfaccia
export type ICustomConfig = yup.InferType<typeof customConfigValidator>;

Estensione dell'interfaccia#

L'estensione dell'interfaccia modifica IAppConfig tramite la Module Augmentation di TypeScript.

E' necessario specificare la chiave sulla quale sarà disponibile la configurazione, che deve essere equivalente al tag XML. Ad esempio la seguente configurazione:

declare module "@favojs/config" {
export interface IAppConfig {
custom: ICustomConfig;
}
}

Richiederà un XML come il seguente:

<config>
<!-- ... -->
<custom>
<example>value</example>
</custom>
</config>

Registrazione su AppConfig#

Per permettere il caricamento da parte di AppConfig della configurazione appena creata, dobbiamo registrarla su AppConfig, tramite il metodo AppConfig.add. Il metodo si occupa di definire una chiave (equivalente al tag XML che verrà letto) con il suo validatore (per validare il contenuto del tag).

CustomModule.ts
import { AppConfig } from "@favojs/config";
import { customConfigValidator } from "./config/CustomConfig";
// ...
AppConfig.add("custom", customConfigValidator);
Posizionamento della chiamata

La registrazione dovrebbe avvenire nel file del modulo (i.e. CustomModule.ts).

  • Se il modulo è dinamico, possiamo inserire la chiamata all'interno del register() che ritorna il DynamicModule.
  • Per un modulo statico, la registrazione può avvenire semplicemente all'inizio del file.
Aggiornato il da Leonardo Ascione