Passa al contenuto principale

@powerduck/conf-patch

@powerduck/conf-patch modifica le configurazioni con un’architettura a due livelli. Applica la semantica RFC 6902 JSON Patch alle stringhe JSON, JSONC e YAML, conserva commenti e formattazione e offre scritture atomiche e blocchi tra processi per Node.js ed Electron.

Perché conf-patch?​

Modificare file di configurazione via codice richiede spesso una scelta: serializzare l’intero documento, rischiando di alterare commenti e formattazione, oppure ricorrere a fragili manipolazioni del testo. conf-patch offre:

  • Modifiche incrementali che conservano i commenti per JSON/JSONC con jsonc-parser e modifiche dell’AST per YAML con yaml. JSON/JSONC evita la serializzazione completa; YAML serializza nuovamente l’AST modificato.
  • Scritture atomiche tramite un file temporaneo seguito da una rinomina, evitando file di destinazione scritti solo in parte.
  • Blocchi tra processi con token di proprietà, attese esponenziali tra i tentativi e recupero dei blocchi obsoleti.
  • Un’API versatile: il livello principale funziona anche nei browser, nelle funzioni Edge e nelle applicazioni con archiviazione IndexedDB.

Architettura a due livelli​

┌──────────────────────────────────────────────────────────────┐
│                     Application code                          │
├──────────────────────────────────────────────────────────────┤
│  File layer (Node.js / Electron only)                         │
│  ┌───────────────┐ ┌────────────────┐ ┌──────────────────┐  │
│  │ readConfigFile │ │ writeConfigFile│ │ patchConfigFile   │  │
│  │ setConfigValue │ │ deleteConfig…  │ │ withFileLock     │  │
│  └──────┬────────┘ └───────┬────────┘ └────────┬─────────┘  │
│         │                  │                   │            │
│  ┌──────▼──────────────────▼───────────────────▼───────────┐ │
│  │           Core layer (browser-safe, zero Node deps)      │ │
│  │  patchContent   setContentValue   deleteContentValue     │ │
│  └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

Livello principale — @powerduck/conf-patch/core (compatibile con il browser)​

Funzioni pure che operano su stringhe, senza node:fs, node:path o API specifiche di Node.js. Questo sottopercorso può essere incluso nel codice per browser, funzioni Edge o service worker.

FunzioneScopo
patchContentApplicare operazioni RFC 6902 a una stringa di configurazione
setContentValueImpostare o creare un valore annidato (con add)
deleteContentValueRimuovere una chiave o un elemento di array (con remove)

Livello file — @powerduck/conf-patch (Node.js / Electron)​

Funzioni asincrone che leggono e scrivono file, aggiungendo scritture atomiche e blocchi al livello principale.

FunzioneScopo
readConfigFileLeggere testo UTF-8 da un percorso o da un URL file://
writeConfigFileScrivere contenuti in modo atomico, con blocco facoltativo
patchConfigFileEseguire una transazione di lettura, modifica e scrittura sotto blocco
setConfigValueImpostare un valore annidato in un file
deleteConfigValueEliminare un valore annidato da un file
withFileLockEseguire un’attività sotto blocco esclusivo
releaseAllLocalLocksRilasciare tutti i blocchi del processo corrente

Formati supportati​

FormatoEstensioneComportamento
JSON.jsonJSON standard. Modifiche incrementali con jsonc-parser.
JSONC.jsoncJSON con commenti e virgole finali. I commenti vengono conservati.
YAML.yaml, .ymlYAML 1.2. Le modifiche dell’AST conservano commenti, ancore e rientri.

detectFormat associa le estensioni a un ConfigFormat. Le altre estensioni generano un errore, salvo specificare esplicitamente format.

Operazioni RFC 6902​

conf-patch implementa un sottoinsieme mirato di RFC 6902. Sono supportate soltanto queste operazioni:

opComportamento
"add"Inserire a un indice di array o aggiungere/sostituire una proprietà di oggetto
"replace"Sostituire un valore esistente; il percorso deve esistere
"remove"Rimuovere una chiave o un elemento esistente; il percorso deve esistere
attenzione

"move", "copy" e "test" non sono supportati. Il tipo JsonPatchOp limita op a "add" | "replace" | "remove".

Note sul comportamento:

  • add a un indice di array inserisce un elemento (RFC 6902). Per sostituire un elemento esistente, usare replace.
  • add richiede che il percorso padre esista già. Creare i genitori prima dei figli.
  • replace e remove richiedono che il percorso di destinazione esista.
  • Con strict: true (predefinito), un’operazione non riuscita genera un’eccezione. Con strict: false, viene saltata e viene registrato un avviso.

Conservazione di commenti e formattazione​

  • JSON/JSONC: le modifiche vengono calcolate come intervalli di testo a partire dall’albero sintattico, conservando commenti circostanti, virgole finali e rientri.
  • YAML: l’AST di yaml viene modificato sul posto e serializzato nuovamente, conservando commenti, ancore, alias e rientri.

Validazione OpenAPI​

conf-patch valida documenti OpenAPI/Swagger tramite un’interfaccia protetta per @powerduck/openapi-parser:

  • validateOpenAPISpec valida contenuti grezzi JSON o YAML.
  • validateOpenAPIFile valida un documento dal suo percorso.
  • La gestione degli input impone limiti di dimensione, restrizioni sui percorsi (allowedRootDirectory), controlli di complessità, scadenze e annullamento con AbortSignal.
  • Gli errori generano OpenApiValidationError con un code interpretabile dal programma.

Passi successivi​

  • Installazione — aggiungere conf-patch e conoscere i due punti di ingresso.
  • Avvio rapido — modificare una stringa nel browser e un file su disco.
  • Riferimento API — tutte le esportazioni, i tipi e le opzioni.
  • Esempi — esempi eseguibili per JSON, YAML, JSONC, validazione OpenAPI e blocchi.