--- title: "Référence d'API — nodefony — config" source: docs/api/core/config.md url: https://nodefony.github.io/nodefony-core/docs/api/core/config/ --- [Documentation](../../../) › [Référence d'API](../../) › [`nodefony`](../) › config > Générée depuis les déclarations de types publiées de `nodefony` **10.0.0-beta.5** : exactement ce que reçoit une application qui l'installe. Cette page n'existe dans aucun dépôt — pour la corriger, on corrige le TSDoc du code. ## `nodefony` `import { … } from "nodefony"` — 86 symboles. ### Fonctions (35) #### `aggregateProvenance` ```ts function aggregateProvenance(provenance: Record | null, key: string): string ``` L'origine d'une clé du CATALOGUE, agrégée depuis la provenance par feuille. #### `appConfigJsonSchema` ```ts function appConfigJsonSchema(): unknown ``` JSON Schema introspectable de la config d'application — destiné au panneau de config Studio (`/nodefony/config`, carte de l'app). Documenté via les `.describe()` du schéma (rôle + défaut de chaque champ). #### `applyEnvShortcuts` ```ts function applyEnvShortcuts(options: Record, schema: unknown, env: Record): IAppliedEnvShortcut[] ``` Pose sur les options d'un module la valeur de chaque raccourci présent dans l'environnement — AVANT la validation Zod du module, qui reste seule juge : une valeur fausse y est refusée et arrête le démarrage. #### `applyResolvedPath` ```ts function applyResolvedPath(target: Record, path: string[], value: unknown, raw?: string, schema?: unknown): boolean ``` Pose `value` dans `target` au `path` donné, en résolvant chaque segment contre les clés EXISTANTES (insensible à la casse). N'altère QUE des chemins déjà présents dans la config (= champs ayant un défaut) — un chemin inconnu n'est pas créé (évite une clé fantôme à la mauvaise casse que le Zod ignorerait silencieusement) : la fonction renvoie alors `false` pour signalement. #### `collectEnvShortcuts` ```ts function collectEnvShortcuts(schema: unknown): IEnvShortcut[] ``` Les raccourcis d'environnement que déclare un JSON Schema de configuration. #### `computeConfigProvenance` ```ts function computeConfigProvenance(resolved: Record, defaults: Record, envPaths?: ReadonlySet): Record ``` Calcule l'origine de chaque valeur feuille de la config résolue d'un module. #### `defineConfig` ```ts function defineConfig>(input: ConfigInput): AppConfigDescriptor ``` Builder unique de la config d'application. #### `defineEnv` ```ts function defineEnv>(catalog: M, source?: Record): { readonly [K in keyof M]: z.infer; } ``` Lit + valide un catalogue de variables d'environnement, une fois, au boot. #### `deriveStoreBackend` ```ts function deriveStoreBackend(store: unknown): string ``` Déduit le nom court du backend d'un store à partir de la classe concrète de son instance (convention de nommage `XxxStore` → `drizzle`, `mongoose`, `redis`, `memory`, `file`). Sert à retrouver le backend RÉEL d'un adapter posé au container quand la brique a été résolue en `"auto"` (l'adapter court-circuite la fabrique nommée). Classe non reconnue → nom de classe brut (honnête). #### `durableStoreRemedy` ```ts function durableStoreRemedy(connectivity: boolean | IStoreConnectivity): string ``` Le REMÈDE à nommer quand une brique durable se retrouve en mémoire. #### `envBoolean` ```ts function envBoolean(opts: BoolOpts & { optional: true; default?: undefined; }): z.ZodType function envBoolean(opts?: BoolOpts): z.ZodType ``` Variable d'env BOOLEAN 12-factor : `1/true/yes/on` → true, `0/false/no/off` → false (insensible à la casse). Absente → `default` (défaut `false`). Valeur hors de ces ensembles → erreur au boot (typo détectée, ex. `tru`). `optional:true` sans `default` → absente = `undefined`. #### `envEnum` ```ts function envEnum(values: T, opts: EnumOpts & { optional: true; }): z.ZodType function envEnum(values: T, opts?: EnumOpts): z.ZodType ``` Variable d'env ENUM (ensemble fermé). Valeur hors liste → erreur au boot. Le type littéral est préservé (`env.X` typé sur l'union exacte). #### `envNumber` ```ts function envNumber(opts: NumOpts & { optional: true; }): z.ZodType function envNumber(opts?: NumOpts): z.ZodType ``` Variable d'env NUMBER (coercée). Valeur non numérique → erreur au boot. #### `envString` ```ts function envString(opts: StrOpts & { optional: true; }): z.ZodType function envString(opts?: StrOpts): z.ZodType ``` Variable d'env STRING. Avec `default` → toujours présente ; `optional:true` → `string | undefined` ; sinon requise (absente → erreur au boot). #### `envVarPlacement` ```ts function envVarPlacement(meta: Pick): EnvVarPlacement ``` Où la variable se pose en production. La déclaration (`placement`) fait foi ; sans elle, un secret va au gestionnaire de secrets et le reste aux variables du déploiement. Seule source de cette décision pour la notice `.env.example`. #### `extractJsonSchemaDefaults` ```ts function extractJsonSchemaDefaults(jsonSchema: unknown): Record ``` Reconstruit l'objet des défauts d'un module depuis son JSON Schema (`z.toJSONSchema`, retourné par `Module.configSchema()`) — utile quand le schéma Zod n'est pas accessible (côté data plane admin). Walk récursif des `properties` : prend `default` quand présent (y compris pour un objet entier), sinon descend. #### `flattenConfigSchema` ```ts function flattenConfigSchema(schema: unknown): ISchemaLeaf[] ``` Aplatit un JSON Schema de module en catalogue de réglages assignables. #### `getConfigReactivity` ```ts function getConfigReactivity(path: string): Reactivity ``` Réactivité d'un champ par son chemin dot-notation ; `boot` par défaut (sûr). #### `getEnvCatalog` ```ts function getEnvCatalog(env: unknown): readonly NamedEnvVarMeta[] ``` Catalogue introspectable des variables déclarées par `defineEnv`, lu sur l'objet `env` retourné. Source unique pour générer `.env.example` (anti-dérive). #### `isConfigDescriptor` ```ts function isConfigDescriptor(value: unknown): value is AppConfigDescriptor ``` Garde de type : `value` est-il un descripteur produit par `defineConfig` ? Utilisé par le Kernel (`loadApp`, Lot 4) pour distinguer une app moderne (`export default defineConfig(…)`) d'une config objet legacy. #### `isSensitiveEnvVar` ```ts function isSensitiveEnvVar(meta: Pick): boolean ``` La variable porte-t-elle un SECRET ? La déclaration (`sensitive`) fait foi ; sans elle, le nom décide, par la même règle que la rédaction des journaux (`pathLooksSecret`). Seule source de cette décision pour la notice `.env.example` et pour `nodefony env`. #### `overlayConfig` ```ts function overlayConfig(packageName: N, overlay: OverlayOf): void ``` Pose un calque de configuration sur la requête courante. #### `parseDatabaseUrl` ```ts function parseDatabaseUrl(url: string): IInfraDatabase ``` Parse l'URL du infra `database` : scheme → famille + dialecte. #### `parseNfEnvOverrides` ```ts function parseNfEnvOverrides(env: NodeJS.ProcessEnv): NfEnvOverride[] ``` Scanne `env` et extrait tous les overrides `NF____`. #### `readResolvedPath` ```ts function readResolvedPath(target: Record, path: string[]): unknown ``` Relit la valeur posée à `path` — la SYMÉTRIQUE de `applyResolvedPath`. #### `readStoreConnector` ```ts function readStoreConnector(store: unknown): string ``` Lit le connecteur ORM d'un store depuis son instance (getter public `connector`), pour le registre des stores — jumeau de `readStoreLocation`. #### `readStoreLocation` ```ts function readStoreLocation(store: unknown): string ``` Lit l'emplacement PHYSIQUE d'un store depuis son instance (getter public `location`), pour l'écran Studio « Stores » — répond à « où mes données sont-elles écrites ? ». Un store fichier (passkeys, TOTP, sessions) expose le chemin de son fichier/dossier ; un store `memory` ou un backend réseau (drizzle/redis/mongoose) n'expose rien → `undefined` (l'UI dérive « en mémoire » ou renvoie à l'infra). #### `renderEnvExample` ```ts function renderEnvExample(catalog: readonly NamedEnvVarMeta[], opts?: { header?: string; }): string ``` Rend le contenu complet de `.env.example` depuis le catalogue. #### `resolveAutoStore` ```ts function resolveAutoStore(kind: StoreKind, infra: IInfra, available: readonly string[], fallback?: string, connectivity?: boolean | IStoreConnectivity): IAutoStoreResolution ``` Résout la sentinelle `"auto"` d'une brique en nom de backend, borné aux backends RÉELLEMENT enregistrés (`available` = `listXStores()` du registre — reflète l'auto-register des adapters chargés). Couverture partielle d'une infra (ex. brique durable sur `redis`) → repli `fallback` avec raison ANNONCÉE, jamais d'échec : le principe « fallback annoncé, pas de dégradation silencieuse » vit dans la raison retournée, que l'appelant DOIT logger. #### `resolveInfra` ```ts function resolveInfra(env?: InfraEnvSource): IInfra ``` Résout les 3 infra déclarée depuis l'environnement. Fonction PURE (aucun kernel) : consommée par le Kernel (1 fois, mémoïsé), par le contexte `defineConfig` (`ctx.infra`) et par les builders de config des modules adapters (drizzle/mongoose/redis) dans leur couche env. #### `sqliteFilenameFromUrl` ```ts function sqliteFilenameFromUrl(url: string): string ``` Fichier SQLite d'une URL `sqlite:` du infra `database`. Formes acceptées : `sqlite::memory:`, `sqlite:./relatif.db`, `sqlite:/abs.db`, `sqlite:///abs.db`. URL vide après le scheme → `:memory:`. #### `use` ```ts function use(name: N, config?: ConfigOf, opts?: UseOptions): ModuleEntryInput ``` Construit une entrée de manifeste `modules` avec config colocalisée + typée. #### `useConfig` ```ts function useConfig(packageName: N): Readonly> ``` Lit la configuration d'un module telle que la voit la requête courante. #### `validateAppConfig` ```ts function validateAppConfig(options: unknown): void ``` Valide la config app résolue ; lève une erreur au message agrégé si invalide. #### `withResolvedPath` ```ts function withResolvedPath(target: Record, path: string[], value: unknown): Record | null ``` Variante « copie sur écriture » de `applyResolvedPath` : rend une NOUVELLE config où `path` vaut `value`, sans jamais écrire dans `target`. ### Constantes (5) #### `AUTO_STORE` ```ts const AUTO_STORE = "auto" ``` Sentinelle des champs `store` : « laisser le framework choisir selon l'infra déclarée ». #### `EMPTY_INFRA` ```ts const EMPTY_INFRA: IInfra ``` Infra vide (rien de déclaré) — fallback sûr quand le kernel est absent (tests). #### `appConfigSchema` ```ts const appConfigSchema: z.ZodObject<{ modules: z.ZodOptional>; locale: z.ZodOptional; templating: z.ZodOptional; orm: z.ZodOptional; packageManager: z.ZodOptional>; domain: z.ZodOptional; domainAlias: z.ZodOptional>; domainCheck: z.Z … ``` Schéma de la config app résolue. Exposé pour l'introspection (Studio : `z.toJSONSchema(appConfigSchema)` → panneau de config + formulaire éditable). #### `configReactivity` ```ts const configReactivity: { readonly "log.active": "hot"; readonly "log.debug": "hot"; readonly "log.requestFormat": "hot"; } ``` Champs applicables À CHAUD (chemin en dot-notation). Tout champ absent est `boot`. #### `defaultAppConfig` ```ts const defaultAppConfig: ResolvedAppConfig ``` Configuration framework par défaut, fusionnée sous la config de l'app au boot. Ne JAMAIS muter à l'exécution (le merge `extend(true, {}, defaultAppConfig, …)` clone ; l'invariant d'immutabilité est couvert par test). ### Interfaces (29) #### `AppConfigDescriptor` ```ts interface AppConfigDescriptor ``` Descripteur de config retourné par `defineConfig`. Opaque : le Kernel appelle `resolve(ctx)` au boot pour obtenir la config fusionnée + validée. - `resolve(ctx: ConfigContext): ResolvedAppConfig` — Résout la config finale : applique le contexte d'env (forme fonction), deep-merge sous les défauts framework, valide (Zod). #### `AppConfigInput` ```ts interface AppConfigInput ``` Forme de la configuration d'une application Nodefony, telle qu'écrite par l'utilisateur dans `nodefony.config.ts`. Tous les champs sont optionnels : ce que l'app n'écrit pas vient de `defaultAppConfig` (deep-merge au resolve). - `modules?: ModuleManifestInput` — Manifeste ordonné des modules chargés (liste + policy + gating `when`). - `locale?: string` — Locale par défaut de l'app (fallback translation/dates), override par requête. - `App?: AppMeta` — Métadonnées d'identité de l'app (auteur, année) — affichées CLI + logs. - `templating?: string` — Moteur de templates des vues controllers (`renderView`). - `orm?: string` — ORM par défaut (commandes CLI + modules sans ORM explicite). - `packageManager?: "npm" | "yarn" | "pnpm" | "bun"` — Gestionnaire de paquets Node.js (commandes install/outdated/build). - `domain?: string` — Domaine d'écoute (un seul, pas de vhost). - `domainAlias?: string[]` — Alias de domaines acceptés (regexps stringifiées), actif si `domainCheck` — validation Host kernel-level (compilée en RegExp). - `domainCheck?: boolean` — Active la validation Host kernel-level (`domain` + `domainAlias`) avant le routing. - `servers?: ServersConfig` — Serveurs HTTP/HTTPS/WS/WSS. - `cluster?: Record` — Topologie cluster (cloud-native, sans PM2). - `shutdownDeadline?: number` — Deadline GLOBALE du shutdown (ms) — au-delà, `Kernel.terminate` force la sortie `code 1` même si un listener `onTerminate` pend (SSE ouvert, store bloqué, module tiers). - `timing?: { enabled?: boolean | null; verbose?: boolean; tooling?: boolean; }` — Chronométrage des requêtes : leur durée, et le détail par phase qui alimente le waterfall (Studio/Playground, debug bar, profiler). - `log?: LogConfig` — Observabilité (Syslog + log backplane). - ``[moduleOverride: `module-${string}`]: unknown`` #### `AppMeta` ```ts interface AppMeta ``` Métadonnées d'identité de l'application (affichées dans la CLI et les logs d'init). - `projectYear?: string` — Année du projet (copyright, bannières). - `locale?: string` — Locale d'affichage des métadonnées. - `authorName?: string` — Nom de l'auteur / mainteneur. - `authorMail?: string` — E-mail de contact de l'auteur. #### `ConfigContext` ```ts interface ConfigContext> ``` Contexte passé à la forme fonction de `defineConfig` — permet de différencier la config par environnement SANS fichier `config..ts` parallèle (D3). - `readonly env: E` — Catalogue des variables d'environnement typées (`defineEnv`, Lot 2). - `readonly infra: IInfra` — Infra déclarée résolus depuis l'environnement (modèle « infra déclarée », Phase 0.8) — `database`/`cache`/`logs`. - `readonly appEnv: string` — Environnement applicatif libre (`APP_ENV`/`NF_ENV`) — granularité métier. - `readonly runtimeEnv: string` — Environnement runtime canonisé (`NODE_ENV`). - `readonly isProd: boolean` — Raccourci `runtimeEnv === "production"`. - `readonly isDev: boolean` — Raccourci `runtimeEnv === "development"`. - `readonly isTest: boolean` — Raccourci `runtimeEnv === "test"`. - `readonly devModules?: boolean` — Les modules `policy: "dev"` sont-ils chargés ? #### `EnvVarMeta` ```ts interface EnvVarMeta ``` Métadonnées INTROSPECTABLES d'une variable du catalogue — capturées à la déclaration (le défaut serait sinon piégé dans la closure `z.preprocess`). Portées par le schéma Zod (clé non-énumérable) puis agrégées par `defineEnv` sur l'objet `env` retourné → alimentent la génération de `.env.example`. - `readonly kind: EnvVarKind` — Nature coercée (`string`/`number`/`boolean`/`enum`). - `readonly optional: boolean` — La variable peut-elle être absente (→ `undefined`) ? - `readonly default?: unknown` — Valeur par défaut déclarée (`undefined` si aucune). - `readonly title?: string` — Titre court, rendu en bandeau au-dessus de la variable dans `.env.example`. - `readonly section?: string` — Section de la notice (« Réseau », « Connexion Keycloak ») — regroupe et numérote. - `readonly description?: string` — Doc (`.describe()`), reprise telle quelle dans `.env.example`. - `readonly example?: string` — Une valeur d'exemple réaliste, rendue en `@example` dans `.env.example`. - `readonly sensitive?: boolean` — La valeur est-elle un secret ? - `readonly defaultNote?: string` — Le défaut quand il vit dans le CODE et non dans le catalogue — rendu sur la ligne « défaut : » de `.env.example` (ex. - `readonly values?: readonly string[]` — Valeurs autorisées (enum uniquement). - `readonly requiredIn?: readonly string[]` — Environnements où la variable est REQUISE, même déclarée `optional`. - `readonly requiredWhen?: string` — Une exigence que le CODE impose sous CONDITION, en clair (« en production, si l'application émet des jetons ») — rendue `@requiredWhen` dans la notice. - `readonly placement?: EnvVarPlacement` — Où la poser en production — absent, déduit (cf `envVarPlacement`). #### `HttpServerConfig` ```ts interface HttpServerConfig ``` Serveur HTTP plain. - `port?: number` — Port d'écoute HTTP plain. #### `HttpsServerConfig` ```ts interface HttpsServerConfig ``` Serveur HTTPS (+ WSS hérité). - `port?: number` — Port d'écoute HTTPS. - `protocol?: "1.1" | "2.0"` — Protocole TLS : `"2.0"` (HTTP/2 + ALPN fallback 1.1) ou `"1.1"` strict. #### `IAppliedEnvShortcut` ```ts interface IAppliedEnvShortcut ``` Un raccourci appliqué, pour le journal du démarrage. - `env: string` - `path: string[]` - `secret: boolean` #### `IAutoStoreResolution` ```ts interface IAutoStoreResolution ``` Choix d'un backend pour `"auto"` + provenance lisible (log de boot, Studio). - `store: string` - `reason: string` #### `IConfigFieldMeta` ```ts interface IConfigFieldMeta ``` Métadonnées Nodefony d'un champ de config Zod, au-delà de la `description`. - `reserved?: boolean` — Réservé à une feature future, non lu en runtime (Studio grise le champ). - `runtimeMutable?: boolean` — Modifiable à chaud : la valeur est relue à chaque usage, donc muter `module.options` prend effet SANS redémarrage. - `kernelDerived?: boolean` — Défaut injecté par le builder à partir du kernel (ex. - `secret?: boolean` — Donnée sensible : à masquer dans Studio et à rédiger dans les logs. - `env?: string` — Variable d'environnement qui règle CE champ (`NF_REDIS_HOST`) — un nom court pour la surcharge `NF____`. #### `IEnvShortcut` ```ts interface IEnvShortcut ``` Un raccourci déclaré sur un champ de configuration. - `env: string` — Nom de la variable (`NF_REDIS_HOST`). - `path: string[]` — Chemin du champ dans la configuration du module. - `kind: string` — Type JSON Schema du champ (`string`, `integer`, `boolean`), `enum` pour une énumération. - `description?: string` — La description du champ (`.describe()`), si le schéma en porte une. - `default?: unknown` — Défaut du schéma, s'il en porte un. - `values?: readonly string[]` — Valeurs admises (énumération). - `secret: boolean` — La valeur ne doit jamais être rendue en clair. - `placement?: EnvVarPlacement` — Où la poser en production, si le schéma le déclare (`.meta({ placement })`). #### `IInfra` ```ts interface IInfra ``` L'infra déclarée — `null` = non déclarée. - `database: IInfraDatabase | null` - `cache: IInfraCache | null` - `logs: IInfraLogs | null` - `forceStore?: string | null` — Override GLOBAL de sélection de store (`NF_STORE`) — force TOUTE brique `auto` vers ce backend, en amont de toute préférence d'infra. #### `IInfraCache` ```ts interface IInfraCache ``` Infra `cache` résolu depuis `NF_REDIS_URL`/`REDIS_URL`. - `url: string` — URL redis déclarée (peut porter des credentials — ne jamais logger brute). #### `IInfraDatabase` ```ts interface IInfraDatabase ``` Infra `database` résolu depuis `NF_DATABASE_URL`/`DATABASE_URL`. - `url: string` — URL déclarée telle quelle (peut porter des credentials — ne jamais logger brute). - `scheme: string` — Scheme normalisé en minuscules, sans `:` (ex. - `family: DatabaseFamily` - `dialect: InfraSqlDialect | null` — Dialecte SQL (famille `sql`) — `null` pour la famille `mongo`. #### `IInfraLogs` ```ts interface IInfraLogs ``` Infra `logs` (relecture backplane) — les DEUX URLs peuvent être présentes. - `lokiUrl?: string` - `opensearchUrl?: string` #### `ISchemaLeaf` ```ts interface ISchemaLeaf ``` - `key: string` — Chemin pointé de la clé, tel qu'on l'écrit dans `use()`. - `path: string[]` — Les mêmes segments, non joints — une clé peut contenir un point. - `values?: string[]` — Valeurs admises, quand le schéma déclare une énumération. - `env?: string` — Variable d'environnement qui règle cette clé (`.meta({ env })`), si le module lui a donné un nom court. - `secret?: boolean` — Le drapeau `secret` TEL QUE le schéma le pose — `true` ou `false` ; absent quand le schéma ne dit rien (c'est alors le NOM qui décide). - `placement?: EnvVarPlacement` — Où poser la variable en production (`.meta({ placement })`), quand le schéma le dit — sinon la règle de `envVarPlacement` décide (secret → `secrets`, sinon `platform`). - `type: string` — Type déclaré. - `default?: unknown` — Défaut déclaré par le schéma, tel quel — `undefined` si le schéma n'en pose aucun. - `description: string` — La phrase écrite dans le schéma (`.describe()`), chaîne vide si aucune. - `note: string` — Ce que les métadonnées Nodefony disent de la clé, en un mot — `réservé`, `secret`, `dérivé du kernel`, `modifiable à chaud`. #### `IStoreResolution` ```ts interface IStoreResolution ``` Résolution EFFECTIVE d'une brique de persistance, capturée au boot par le consommateur (au moment exact où il pose son store au container) et retenue dans le registre du Kernel (`IKernel.registerStoreResolution`). C'est la VÉRITÉ vécue — y compris les replis annoncés du lot 4 (session → `"files"` en dev) — pas une re-dérivation à la volée. Alimente l'écran Studio « Stores ». - `brick: string` — Identifiant de la brique (ex. - `nature: StoreKind` — Nature de la donnée — pilote la durabilité affichée (`StoreKind`). - `configured: string` — Valeur configurée telle quelle : `"auto"` (sentinelle) ou un backend explicite. - `resolved: string` — Backend effectivement résolu et posé au runtime. - `available: readonly string[]` — Backends RÉELLEMENT enregistrés pour cette brique (`listXStores()`), capturés par le consommateur — évite à l'endpoint d'importer les registres (le cœur `@nodefony/framework` ne peut pas dépendre de ` … - `provenance: StoreProvenance` — Provenance : `"infra"` (résolu depuis l'infra déclarée, `configured === "auto"`) ou `"explicit"` (backend nommé dans la config/env de l'app). - `reason: string` — Raison lisible (FR) de la résolution — de `resolveAutoStore` ou construite. - `configPath?: string` — Chemin du champ de config (ex. - `location?: string` — Emplacement PHYSIQUE lisible du store, lu depuis l'instance au boot (`readStoreLocation`) — base SQLite pour `drizzle`. - `connector?: string` — Connecteur ORM qui porte la brique, lu depuis l'instance (`readStoreConnector`). #### `LogConfig` ```ts interface LogConfig ``` Observabilité — Syslog Nodefony + log backplane. - `active?: boolean` — Master switch des logs. - `debug?: string | string[]` — Filtre des sources DEBUG : `"*"` (tout), `[]` (aucun), `["router"]` (ciblé). - `requestFormat?: "auto" | "default" | "pretty" | "json"` — Format de log émis par HttpKernel pour chaque requête finie. - `buffered?: boolean | "auto"` — Bufférisation de la sortie console (`"auto"` = bufférise hors TTY). - `driver?: "stdout" | "file" | "null"` — Sink d'écriture des logs : `"stdout"` (cloud-native), `"file"`, `"null"` (bench). - `format?: "text" | "json"` — Forme des lignes écrites par le sink : `"text"` (lisible) ou `"json"` (un enregistrement par ligne — ce qu'un collecteur transporte, et ce que la relecture Loki/OpenSearch sait relire). - `dir?: string` — Répertoire des logs (fichiers `.log` + JSONL queryable + viewer Studio), résolu sous `process.cwd()`. - `file?: LogFileConfig` — Options du sink fichier. - `maxStack?: number` — Profondeur du ring de relecture du backplane de log (driver `memory`). - `queryFile?: LogQueryFileConfig` — Options du driver de relecture `file` (query plane JSONL). - `queryDriver?: string` — Driver de RELECTURE du log backplane (≠ sink d'écriture). - `loki?: LokiDestinationConfig` — Destination Loki (active si `queryDriver === "loki"`). - `opensearch?: OpenSearchDestinationConfig` — Destination OpenSearch (active si `queryDriver === "opensearch"`). #### `LogDestinationConfig` ```ts interface LogDestinationConfig ``` Destination prod queryable du log backplane (Loki / OpenSearch). - `url: string` — URL HTTP de la destination. - `write?: boolean` — `false` = relecture SEULE : l'application n'y envoie rien, un collecteur de l'hébergeur s'en charge (avec `log.format: "json"`), et la console d'administration relit ce qu'il a poussé. - `username?: string` — Utilisateur de l'authentification basique. - `password?: string` — Mot de passe de l'authentification basique (secret : jamais commité). - `headers?: Record` — En-têtes HTTP ajoutés à l'envoi comme à la relecture (proxy d'authentification…). - `timeoutMs?: number` — Délai d'une requête vers la destination, en millisecondes. - `batchSize?: number` — Lignes regroupées par envoi. - `flushIntervalMs?: number` — Intervalle maximal entre deux envois, en millisecondes. - `maxQueue?: number` — Lignes gardées en attente au plus ; au-delà, les plus anciennes sont écartées. #### `LogFileConfig` ```ts interface LogFileConfig ``` Sortie fichier du Syslog. - `path?: string` — Chemin explicite du fichier de log (sink `file`). - `sync?: boolean` — Écriture synchrone (`writeSync`) par worker au lieu du buffer async. #### `LokiDestinationConfig` ```ts interface LokiDestinationConfig extends LogDestinationConfig ``` Destination Grafana Loki : une `LogDestinationConfig` plus son sélecteur. - `labels?: Record` — Étiquettes de flux : posées à l'envoi, et sélecteur de la relecture. - `tenantId?: string` — Locataire d'un Loki multi-tenant (en-tête `X-Scope-OrgID`). - `maxScanLines?: number` — Lignes rapatriées au plus par une relecture, avant filtrage. #### `ModuleEntryInput` ```ts interface ModuleEntryInput ``` Entrée détaillée du manifeste `modules` (forme objet). Une `string` nue équivaut à `{ name, policy: "optional" }`. - `name: KnownModule` — Nom du module à charger (résolu par `import()` dynamique au boot). - `policy?: ModulePolicy` — Politique de chargement. - `when?: (config: ResolvedAppConfig) => boolean` — Garde évaluée sur la config résolue ; `false` → module ignoré (0 coût). - `config?: Record` — Config colocalisée du module (deep-mergée sous sa config DEFAULT au boot par le Kernel, avant la validation Zod du module). #### `NamedEnvVarMeta` ```ts interface NamedEnvVarMeta extends EnvVarMeta ``` `EnvVarMeta` + le nom de la variable (clé du catalogue). - `readonly name: string` #### `NfEnvOverride` ```ts interface NfEnvOverride ``` Un override d'environnement résolu (issu d'une variable `NF__…`). - `readonly envKey: string` — Variable d'env d'origine (ex. - `readonly moduleSeg: string` — Segment module normalisé minuscule (ex. - `readonly path: string[]` — Chemin dans la config du module, segments minuscules (ex. - `readonly value: unknown` — Valeur coercée (booléen / nombre / tableau CSV / objet JSON / chaîne). - `readonly raw: string` — La chaîne BRUTE, telle que l'environnement la porte. #### `NodefonyModuleConfig` ```ts interface NodefonyModuleConfig ``` Registre AUGMENTABLE des configs par module — vide par défaut, enrichi par chaque module via *declaration merging* sur le package `nodefony` : #### `NodefonyModuleOverlay` ```ts interface NodefonyModuleOverlay ``` Registre AUGMENTABLE des calques acceptés par module — la forme de la liste blanche, déclarée par chaque module comme `NodefonyModuleConfig` : #### `OpenSearchDestinationConfig` ```ts interface OpenSearchDestinationConfig extends LogDestinationConfig ``` Destination OpenSearch : une `LogDestinationConfig` plus son index. - `index?: string` — Index écrit à l'envoi et lu à la relecture. - `maxHits?: number` — Documents rapatriés au plus par une relecture, avant filtrage. #### `ServersConfig` ```ts interface ServersConfig ``` Serveurs réseau HTTP/HTTPS/WS/WSS (un seul domaine, pas de vhost). - `statics?: boolean` — Active le serveur de fichiers statiques (assets, uploads). - `http?: HttpServerConfig | false` — Serveur HTTP plain. - `https?: HttpsServerConfig | false` — Serveur HTTPS (le WSS en hérite). - `h2c?: H2cServerConfig` — Serveur HTTP/2 en clair (h2c) pour un proxy inverse — désactivé par défaut. - `ws?: Record` — Serveur WebSocket (hérite du HTTP associé). - `wss?: Record` — Serveur WebSocket Secure (hérite du HTTPS associé). - `portPolicy?: "auto" | "strict"` — Que faire quand le port désiré est DÉJÀ OCCUPÉ. - `portRetryAttempts?: number` — En `portPolicy: "auto"`, nombre de ports essayés après le port désiré. #### `UseOptions` ```ts interface UseOptions ``` Options de chargement passées à `use` (3ᵉ argument). - `policy?: ModulePolicy` — Politique de chargement. - `when?: (config: ResolvedAppConfig) => boolean` — Garde évaluée sur la config résolue ; `false` → module ignoré (0 coût). ### Types (17) #### `AppConfig` ```ts type AppConfig = z.infer ``` Type inféré de la config app (source unique TS ↔ runtime). #### `ConfigInput` ```ts type ConfigInput> = AppConfigInput | (ctx: ConfigContext) => AppConfigInput ``` Entrée de `defineConfig` : soit un objet de config, soit une fonction `(ctx) => objet` pour différencier par environnement (D3). #### `ConfigOf` ```ts type ConfigOf = N extends keyof NodefonyModuleConfig ? NodefonyModuleConfig[N] : Record ``` Type de la config d'un module `N` : sa forme enregistrée dans `NodefonyModuleConfig` si elle existe, sinon un objet libre (le module n'a pas (encore) publié son type de config — toujours utilisable). #### `ConfigOrigin` ```ts type ConfigOrigin = "default" | "app" | "env" ``` Origine d'une valeur de configuration résolue. #### `DatabaseFamily` ```ts type DatabaseFamily = "sql" | "mongo" ``` Famille du infra `database` — pilote le choix de l'adapter (drizzle/mongoose). #### `EnvVarKind` ```ts type EnvVarKind = "string" | "number" | "boolean" | "enum" ``` Nature coercée d'une variable d'env du catalogue. #### `EnvVarPlacement` ```ts type EnvVarPlacement = "platform" | "secrets" | "workstation" ``` Où une variable se pose en PRODUCTION — la colonne « où la poser » de la notice. #### `IStoreConnectivity` ```ts type IStoreConnectivity = { readonly allowed: true; } | { readonly allowed: false; readonly cause: "no-external-services" | "schema-work"; } ``` Un run peut-il confier ses briques `auto` à un backend CONNECTÉ — et sinon, pourquoi ? La cause fait la phrase : accuser `externalServices` une commande qui l'a déclaré, mais qui travaille le schéma, enverrait corriger ce qui va. #### `InfraEnvSource` ```ts type InfraEnvSource = Record ``` Source d'environnement (forme de `process.env`) — injectable pour les tests. #### `InfraSqlDialect` ```ts type InfraSqlDialect = "sqlite" | "postgres" | "mysql" ``` Dialecte SQL déduit du scheme de l'URL du infra `database`. #### `KnownModule` ```ts type KnownModule = "@nodefony/http" | "@nodefony/framework" | "@nodefony/security" | "@nodefony/user" | "@nodefony/frontend" | "@nodefony/studio" | "@nodefony/documentation" | "@nodefony/realtime" | "@nodefony/redis" | "@nodefony/drizzle" | "@nodefony/mongoose" | (string & {}) ``` Noms de modules connus du framework — proposés à l'autocomplétion tout en **acceptant n'importe quel module tiers** (astuce `string & {}` : conserve les littéraux connus dans la complétion sans fermer le type aux strings arbitraires). #### `ModuleManifestInput` ```ts type ModuleManifestInput = ReadonlyArray ``` Manifeste ORDONNÉ des modules de l'application (position = ordre de chargement). `policy`/`when` filtrent, ne réordonnent jamais. #### `OverlayOf` ```ts type OverlayOf = N extends keyof NodefonyModuleOverlay ? NodefonyModuleOverlay[N] : never ``` Calque accepté par le module `N` — `never` s'il n'en déclare pas. #### `Reactivity` ```ts type Reactivity = "hot" | "boot" ``` Réactivité d'un champ de config. #### `ResolvedAppConfig` ```ts type ResolvedAppConfig = AppConfigInput ``` Configuration résolue : `AppConfigInput` après deep-merge avec les défauts framework et validation Zod. Même forme structurelle (le merge remplit les valeurs ; le Kernel lit défensivement avec ses propres fallbacks résiduels). #### `StoreKind` ```ts type StoreKind = "durable" | "ephemeral" | "session" ``` Nature de la donnée d'une brique — pilote l'ordre de préférence des backends : - `durable` (tokens, passkeys, audit, webhooks, user) → infra database. - `ephemeral` (idempotence) → infra cache, sinon database. - `session` → cache, sinon database, sinon fallback fichier. #### `StoreProvenance` ```ts type StoreProvenance = "infra" | "explicit" ``` Catégorie de provenance d'un store résolu (dérivée de la valeur configurée). --- [← Toutes les références d'API](../../)