Validation et génération de schéma

Deux fonctions couvrent la moitié hors-ligne de l'API : vérifier une configuration sans rien démarrer, et émettre le JSON Schema qui décrit toutes les configurations.

validateConfig(config)

Décode une valeur inconnue face à AppSchema. La fonction ne lève jamais : une configuration invalide revient sous forme de données, ce qui permet de signaler plusieurs problèmes d'un coup au lieu de mourir sur le premier.

import { validateConfig } from 'sovrium'

const result = validateConfig({ name: 'My App' })

if (result.valid) {
  console.log(result.config.name)
} else {
  result.errors.forEach((error) => console.error(error))
}

ValidateConfigResult

Le résultat est une union discriminée, pas un enregistrement à champs optionnels. Affinez sur valid avant de lire quoi que ce soit d'autre — TypeScript ne vous laissera pas faire autrement.

Quand	Forme
valid: true	{ valid: true, config: AppConfig }
valid: false	{ valid: false, errors: readonly string[] }

errors contient des chaînes de caractères, une par ligne de l'arbre de décodage formaté, chacune nommant le chemin en échec et sa raison. Sur la branche de succès, la propriété errors n'existe pas du tout ; sur la branche d'échec, config non plus.

import { validateConfig } from 'sovrium'

const untrusted: unknown = JSON.parse(await Bun.file('app.json').text())
const result = validateConfig(untrusted)

if (!result.valid) {
  console.error(`Invalid config:\n${result.errors.join('\n')}`)
  process.exit(1)
}

// `result.config` est un AppConfig ici, et seulement ici.
console.log(`Validated ${result.config.name}`)

generateAppJsonSchema()

Produit le JSON Schema (Draft-07) de la configuration d'application sous forme d'objet simple — le même document qu'affiche sovrium schema.

import { generateAppJsonSchema } from 'sovrium'

const schema = generateAppJsonSchema()

await Bun.write('app.schema.json', JSON.stringify(schema, null, 2))

Elle ne prend aucun argument et ne lit rien de l'environnement : le schéma est dérivé d'AppSchema lui-même, sa sortie ne dépend donc que de la version de Sovrium. On peut ainsi le régénérer en CI et comparer les différences — un changement dans le fichier est un changement du schéma, jamais de la machine.

Un usage courant consiste à figer le schéma à côté de la configuration, pour que les éditeurs valident face à la version exacte que vous déployez :

// scripts/sync-schema.ts — à exécuter après chaque montée de version
import { generateAppJsonSchema } from 'sovrium'

await Bun.write('app.schema.json', JSON.stringify(generateAppJsonSchema(), null, 2))

# app.yaml
# yaml-language-server: $schema=./app.schema.json
name: my-app

Pages associées

• Aperçu de l'API TypeScript — AppConfig et les autres fonctions.
• Valider une configuration — le vérificateur du CLI et ses balayages supplémentaires.
• Schéma JSON — les URLs du schéma hébergé.
• Configuration de l'éditeur — y brancher VS Code ou JetBrains.