Configurations TypeScript

Une configuration peut être un module TypeScript plutôt qu'un fichier YAML ou JSON. Le CLI accepte app.ts partout où il accepte app.yaml. La différence se joue entièrement dans votre éditeur, où chaque propriété, type de champ et type de composant est vérifié au fil de la frappe.

Aucun npm là-dedans. Une configuration TypeScript ne demande ni package.json, ni node_modules, ni étape d'installation. Les types sont embarqués dans le binaire, et une seule commande les écrit à côté de votre configuration.

Mise en place

Lancez ceci dans le répertoire qui contient votre configuration :

sovrium types

Deux fichiers apparaissent, et les deux sont nécessaires :

La déclaration seule est inerte. Sans tsconfig.json, tsc ne l'intègre jamais au programme et chaque configuration échoue sur TS2307: Cannot find module 'sovrium'.

Écrivez maintenant la configuration :

// app.ts
import type { AppConfig } from 'sovrium'

export default {
  name: 'my-app',
  version: '1.0.0',
  description: 'A simple todo list',
  tables: [
    {
      id: 1,
      name: 'tasks',
      fields: [
        { id: 1, name: 'title', type: 'single-line-text', required: true },
        { id: 2, name: 'done', type: 'checkbox', default: false },
      ],
    },
  ],
} satisfies AppConfig

Elle se lance avec les mêmes commandes que n'importe quel autre format :

sovrium start app.ts
sovrium validate app.ts

Pour obtenir les trois fichiers d'un coup, échafaudez avec sovrium init --typescript. La commande écrit ensemble app.ts, sovrium.d.ts et tsconfig.json, si bien qu'un répertoire neuf passe le typage et la validation du premier coup.

Pourquoi l'import ne porte que le type

L'import s'écrit import type, et l'objet est vérifié avec satisfies. Ni l'un ni l'autre n'est une question de style.

import type disparaît avant que le binaire ne regarde. Sovrium ne résout pas les spécificateurs de paquet, donc une valeur importée depuis sovrium n'aurait rien à résoudre au démarrage. Un import de type seul s'efface à la transpilation : le spécificateur n'est donc jamais résolu du tout. C'est ce qui permet à une configuration typée de fonctionner sans rien d'installé.

La déclaration exporte des types et jamais une valeur. C'est délibéré, et cela rend l'erreur inatteignable plutôt que simplement déconseillée. Une fonction utilitaire logée dans ce fichier passerait le typage sans broncher puis refuserait de démarrer, soit la pire forme que puisse prendre une panne : tsc sort en 0, la configuration part en production, et l'erreur arrive à sovrium start. Sans aucune valeur à importer, un import de valeur échoue dans votre éditeur pour la raison ordinaire qu'un tel export n'existe pas. Un garde-fou au build fait échouer la publication si une valeur venait à s'y glisser.

satisfies vaut mieux qu'une annotation AppConfig. Il confronte le littéral au type sans l'élargir : l'export conserve sa forme exacte, et une propriété mal orthographiée reste une erreur de propriété excédentaire.

Composer avec des imports

$ref est un mécanisme YAML et JSON. TypeScript en possède déjà un. La déclaration exporte un type par section : scindez donc la configuration en modules, puis assemblez-les.

// config/tables.ts
import type { TableConfig } from 'sovrium'

export const companies: TableConfig = {
  id: 1,
  name: 'Companies',
  fields: [
    { id: 1, name: 'name', type: 'single-line-text', required: true },
    { id: 2, name: 'website', type: 'url' },
  ],
}

// app.ts
import type { AppConfig } from 'sovrium'
import { companies } from './config/tables'

export default {
  name: 'crm-workspace',
  tables: [companies],
} satisfies AppConfig

TableConfig, PageConfig, AuthConfig, ThemeConfig et les autres types de section proviennent tous de la même déclaration. Et comme la configuration est un vrai module, elle peut aussi être calculée : lire une valeur dans l'environnement, générer une table par entité, dériver des routes depuis une liste.

Après une mise à jour du binaire

Relancez sovrium types. La déclaration décrit le schéma du binaire qui l'a écrite : périmée, elle contredit silencieusement le moteur que vous exécutez désormais. La réécrire à chaque exécution est précisément ce qui rend inatteignable un décalage entre vos types et votre binaire.

Votre tsconfig.json, lui, n'est pas touché, car il vous appartient à ce stade : chemins d'alias, JSX, options de compilation plus strictes. Une seule chose doit rester vraie, et la commande le rappelle quand elle renonce à y toucher. sovrium.d.ts doit demeurer dans le programme TypeScript, ce qui est le cas tant qu'une entrée include ou files ne restreint pas le motif par défaut au point de l'exclure.

Quand préférer TypeScript

Les deux décrivent le même objet : ce n'est donc pas une porte à sens unique. Une configuration YAML se transcrit à la main en TypeScript, et réciproquement.

Pages associées

• Fichiers de configuration : YAML et JSON — les deux autres formats.
• Configurations multi-fichiers — l'équivalent YAML et JSON des imports.
• Schéma JSON — les mêmes garanties pour les auteurs YAML.
• CLI : commandes de projet — sovrium types et sovrium init.