Référence d'API — nodefony — config

stable

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#

function aggregateProvenance(provenance: Record<string, string> | null, key: string): string

L’origine d’une clé du CATALOGUE, agrégée depuis la provenance par feuille.

appConfigJsonSchema#

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#

function applyEnvShortcuts(options: Record<string, unknown>, schema: unknown, env: Record<string, string>): 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#

function applyResolvedPath(target: Record<string, unknown>, 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#

function collectEnvShortcuts(schema: unknown): IEnvShortcut[]

Les raccourcis d’environnement que déclare un JSON Schema de configuration.

computeConfigProvenance#

function computeConfigProvenance(resolved: Record<string, unknown>, defaults: Record<string, unknown>, envPaths?: ReadonlySet<string>): Record<string, ConfigOrigin>

Calcule l’origine de chaque valeur feuille de la config résolue d’un module.

defineConfig#

function defineConfig<E = Record<string, unknown>>(input: ConfigInput<E>): AppConfigDescriptor

Builder unique de la config d’application.

defineEnv#

function defineEnv<M extends Record<string, z.ZodType>>(catalog: M, source?: Record<string, string>): { readonly [K in keyof M]: z.infer<M[K]>; }

Lit + valide un catalogue de variables d’environnement, une fois, au boot.

deriveStoreBackend#

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 <Backend>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#

function durableStoreRemedy(connectivity: boolean | IStoreConnectivity): string

Le REMÈDE à nommer quand une brique durable se retrouve en mémoire.

envBoolean#

function envBoolean(opts: BoolOpts & { optional: true; default?: undefined; }): z.ZodType<boolean>
function envBoolean(opts?: BoolOpts): z.ZodType<boolean>

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#

function envEnum<const T extends readonly [ string, ...string[] ]>(values: T, opts: EnumOpts<T[number]> & { optional: true; }): z.ZodType<T[number]>
function envEnum<const T extends readonly [ string, ...string[] ]>(values: T, opts?: EnumOpts<T[number]>): z.ZodType<T[number]>

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#

function envNumber(opts: NumOpts & { optional: true; }): z.ZodType<number>
function envNumber(opts?: NumOpts): z.ZodType<number>

Variable d’env NUMBER (coercée). Valeur non numérique → erreur au boot.

envString#

function envString(opts: StrOpts & { optional: true; }): z.ZodType<string>
function envString(opts?: StrOpts): z.ZodType<string>

Variable d’env STRING. Avec default → toujours présente ; optional:true → string | undefined ; sinon requise (absente → erreur au boot).

envVarPlacement#

function envVarPlacement(meta: Pick<NamedEnvVarMeta, "name" | "sensitive" | "placement">): 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#

function extractJsonSchemaDefaults(jsonSchema: unknown): Record<string, unknown>

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#

function flattenConfigSchema(schema: unknown): ISchemaLeaf[]

Aplatit un JSON Schema de module en catalogue de réglages assignables.

getConfigReactivity#

function getConfigReactivity(path: string): Reactivity

Réactivité d’un champ par son chemin dot-notation ; boot par défaut (sûr).

getEnvCatalog#

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#

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#

function isSensitiveEnvVar(meta: Pick<NamedEnvVarMeta, "name" | "sensitive">): 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#

function overlayConfig<N extends string>(packageName: N, overlay: OverlayOf<N>): void

Pose un calque de configuration sur la requête courante.

parseDatabaseUrl#

function parseDatabaseUrl(url: string): IInfraDatabase

Parse l’URL du infra database : scheme → famille + dialecte.

parseNfEnvOverrides#

function parseNfEnvOverrides(env: NodeJS.ProcessEnv): NfEnvOverride[]

Scanne env et extrait tous les overrides NF__<MODULE>__<CHEMIN…>.

readResolvedPath#

function readResolvedPath(target: Record<string, unknown>, path: string[]): unknown

Relit la valeur posée à path — la SYMÉTRIQUE de applyResolvedPath.

readStoreConnector#

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#

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#

function renderEnvExample(catalog: readonly NamedEnvVarMeta[], opts?: { header?: string; }): string

Rend le contenu complet de .env.example depuis le catalogue.

resolveAutoStore#

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#

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#

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#

function use<N extends KnownModule>(name: N, config?: ConfigOf<N>, opts?: UseOptions): ModuleEntryInput

Construit une entrée de manifeste modules avec config colocalisée + typée.

useConfig#

function useConfig<N extends string>(packageName: N): Readonly<ConfigOf<N>>

Lit la configuration d’un module telle que la voit la requête courante.

validateAppConfig#

function validateAppConfig(options: unknown): void

Valide la config app résolue ; lève une erreur au message agrégé si invalide.

withResolvedPath#

function withResolvedPath(target: Record<string, unknown>, path: string[], value: unknown): Record<string, unknown> | null

Variante « copie sur écriture » de applyResolvedPath : rend une NOUVELLE config où path vaut value, sans jamais écrire dans target.

Constantes (5)#

AUTO_STORE#

const AUTO_STORE = "auto"

Sentinelle des champs store : « laisser le framework choisir selon l’infra déclarée ».

EMPTY_INFRA#

const EMPTY_INFRA: IInfra

Infra vide (rien de déclaré) — fallback sûr quand le kernel est absent (tests).

appConfigSchema#

const appConfigSchema: z.ZodObject<{ modules: z.ZodOptional<z.ZodArray<z.ZodUnknown>>; locale: z.ZodOptional<z.ZodString>; templating: z.ZodOptional<z.ZodString>; orm: z.ZodOptional<z.ZodString>; packageManager: z.ZodOptional<z.ZodEnum<{ bun: "bun"; npm: "npm"; pnpm: "pnpm"; yarn: "yarn"; }>>; domain: z.ZodOptional<z.ZodString>; domainAlias: z.ZodOptional<z.ZodArray<z.ZodString>>; 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#

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#

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#

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#

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<string, unknown> — 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#

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#

interface ConfigContext<E = Record<string, unknown>>

Contexte passé à la forme fonction de defineConfig — permet de différencier la config par environnement SANS fichier config.<env>.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#

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#

interface HttpServerConfig

Serveur HTTP plain.

• port?: number — Port d’écoute HTTP plain.

HttpsServerConfig#

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#

interface IAppliedEnvShortcut

Un raccourci appliqué, pour le journal du démarrage.

• env: string
• path: string[]
• secret: boolean

IAutoStoreResolution#

interface IAutoStoreResolution

Choix d’un backend pour "auto" + provenance lisible (log de boot, Studio).

• store: string
• reason: string

IConfigFieldMeta#

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__<MODULE>__<CHEMIN>.

IEnvShortcut#

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#

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#

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#

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#

interface IInfraLogs

Infra logs (relecture backplane) — les DEUX URLs peuvent être présentes.

• lokiUrl?: string
• opensearchUrl?: string

ISchemaLeaf#

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#

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#

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#

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<string, string> — 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#

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#

interface LokiDestinationConfig extends LogDestinationConfig

Destination Grafana Loki : une LogDestinationConfig plus son sélecteur.

• labels?: Record<string, string> — É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#

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<string, unknown> — Config colocalisée du module (deep-mergée sous sa config DEFAULT au boot par le Kernel, avant la validation Zod du module).

NamedEnvVarMeta#

interface NamedEnvVarMeta extends EnvVarMeta

EnvVarMeta + le nom de la variable (clé du catalogue).

• readonly name: string

NfEnvOverride#

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#

interface NodefonyModuleConfig

Registre AUGMENTABLE des configs par module — vide par défaut, enrichi par chaque module via declaration merging sur le package nodefony :

NodefonyModuleOverlay#

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#

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#

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<string, unknown> — Serveur WebSocket (hérite du HTTP associé).
• wss?: Record<string, unknown> — 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#

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#

type AppConfig = z.infer<typeof appConfigSchema>

Type inféré de la config app (source unique TS ↔ runtime).

ConfigInput#

type ConfigInput<E = Record<string, unknown>> = AppConfigInput | (ctx: ConfigContext<E>) => AppConfigInput

Entrée de defineConfig : soit un objet de config, soit une fonction (ctx) => objet pour différencier par environnement (D3).

ConfigOf#

type ConfigOf<N extends KnownModule> = N extends keyof NodefonyModuleConfig ? NodefonyModuleConfig[N] : Record<string, unknown>

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#

type ConfigOrigin = "default" | "app" | "env"

Origine d’une valeur de configuration résolue.

DatabaseFamily#

type DatabaseFamily = "sql" | "mongo"

Famille du infra database — pilote le choix de l’adapter (drizzle/mongoose).

EnvVarKind#

type EnvVarKind = "string" | "number" | "boolean" | "enum"

Nature coercée d’une variable d’env du catalogue.

EnvVarPlacement#

type EnvVarPlacement = "platform" | "secrets" | "workstation"

Où une variable se pose en PRODUCTION — la colonne « où la poser » de la notice.

IStoreConnectivity#

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#

type InfraEnvSource = Record<string, string>

Source d’environnement (forme de process.env) — injectable pour les tests.

InfraSqlDialect#

type InfraSqlDialect = "sqlite" | "postgres" | "mysql"

Dialecte SQL déduit du scheme de l’URL du infra database.

KnownModule#

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#

type ModuleManifestInput = ReadonlyArray<KnownModule | ModuleEntryInput>

Manifeste ORDONNÉ des modules de l’application (position = ordre de chargement). policy/when filtrent, ne réordonnent jamais.

OverlayOf#

type OverlayOf<N extends string> = N extends keyof NodefonyModuleOverlay ? NodefonyModuleOverlay[N] : never

Calque accepté par le module N — never s’il n’en déclare pas.

Reactivity#

type Reactivity = "hot" | "boot"

Réactivité d’un champ de config.

ResolvedAppConfig#

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#

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#

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