Référence d'API — nodefony — racine
stable
Documentation › Référence d’API › nodefony › racine
Générée depuis les déclarations de types publiées de
nodefony10.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" — 36 symboles.
Classes (8)#
Cli#
class Cli extends Service
options: CliDefaultOptionsdebug: DebugTypeenvironment: EnvironmentTypecommander: typeof program | nullprotected commands: Record<string, Command>pid: number | nullinteractive: booleanunhandledRejections: Map<Promise<unknown>, string>response: Record<string, any>timers: Record<string, string>version: stringclc: ClcblankLine: () => voidcolumns: numberrows: numberprotected shuttingDown: boolean— Vrai dès le 1ᵉʳ signal d’arrêt reçu.protected static readonly SIGNUM: Record<string, number>— Numéros POSIX → code de sortie forcé128 + signumau 2ᵉ signal.constructor(name?: string)constructor(name: string, options: CliDefaultOptions)constructor(name: string, container: Container | null, options: CliDefaultOptions)constructor(name: string, container: Container | null, notificationsCenter: Event | false, options: CliDefaultOptions)protected handleSignals(): voidprotected trackProcessListener(off: () => void, signal?: boolean): void— Mémorise DE QUOI retirer un listener deprocess.releaseProcessListeners(): number— Retire tous les listeners que cette instance a posés surprocess.releaseSignalListeners(): number— Retire les gestionnaires de SIGNAUX de cette instance — et rien d’autre.start(): Promise<Cli | Kernel>idle(): { resolve: null; promise: Promise<unknown>; reject: null; }checkVersion(version?: string | semver.SemVer | null): stringshowAsciify(name?: string | null): Promise<this>showBanner(): string | nulllistenRejection(): voidsetPid(): numbersetProcessTitle(name?: string): stringlogEnv(): stringinitCommander(): typeof program | nullinitUi(): voidgetFonts(): Promise<void>asciify(txt: string, options?: object, callback?: (error: Error, data: string) => void): Promise<string>parse(argv?: string[], options?: ParseOptions): CommanderCommandparseAsync(argv?: string[], options?: ParseOptions): Promise<CommanderCommand>clearCommand(): voidrunCommand(cmd: string, args?: any[]): CommanderCommandrunCommandAsync(cmd: string, args?: any[]): Promise<CommanderCommand>setCommandOption(flags: string, description?: string, defaultValue?: string | boolean | string[]): CommanderCommandsetCommandVersion(version: string): CommanderCommandsetCommand(nameAndArgs: string, description: string, options?: ExecutableCommandOptions): CommanderCommandaddCommand(cliCommand: new (cli: this) => Command): CommandhasCommand(name: string): booleangetCommand(name: string): Command | nullshowHelp(quit: boolean, context: HelpContext): void | neverdisplayTable(datas: (HorizontalTableRow | VerticalTableRow | CrossTableRow)[] | null, options: TableConstructorOptions, syslog?: Syslog | null): Table.Tablestatic niceBytes(x: string | number): stringstatic niceUptime(date: Date | number | string, suffix?: boolean): string— Temps relatif lisible (“a few seconds ago”, “24 years ago”) — natif viaIntl.RelativeTimeFormat(remplacemoment().fromNow(), dep supprimée).static niceDate(date: Date | number | string, format?: string): string— Formate une date selon des tokensmoment-like (YYYY MM DD HH mm ss SSS) en heure locale — natif (remplacemoment().format(), dep supprimée).clear(): voidreset(): voidresize(): voidcreateDirectory(myPath: fs.PathLike, mode?: fs.MakeDirectoryOptions | fs.Mode | null, force?: boolean): Promise<FileClass>existsSync(myPath: fs.PathLike): booleanexists(myPath: fs.PathLike, mode?: number, callback?: fs.NoParamCallback): booleanterminate(code?: number, quiet?: boolean): Promise<void>static quit(code: number): voidstartTimer(name: string): voidstopTimer(name?: string | null): void— Arrête un timer et affiche le temps écoulé ; sans nom, arrête tous les timers.getCommandManager(manager: string): "bun" | "npm" | "npm.cmd" | "pnpm" | "pnpm.cmd" | "yarn" | "yarn.cmd"— Nom de l’exécutable d’un gestionnaire de paquets sur cette plateforme.runPackageManager(argv: string[], cwd: string, env: EnvironmentType, manager: string): Promise<number | Error>npm(argv?: string[], cwd?: string, env?: EnvironmentType): Promise<number | Error>yarn(argv?: string[], cwd?: string, env?: EnvironmentType): Promise<number | Error>pnpm(argv?: string[], cwd?: string, env?: EnvironmentType): Promise<number | Error>bun(argv?: string[], cwd?: string, env?: EnvironmentType): Promise<number | Error>spawn(command: string, args: readonly string[], options: SpawnOptions, close?: (code: number) => void | null): Promise<unknown>spawnSync(command: string, args: readonly string[], options: SpawnSyncOptionsWithStringEncoding): SpawnSyncReturns<string>
Container#
class Container implements IContainer
Dependency Injection container — registers services by name and exposes them to the rest of the framework.
protoService: ProtoServiceprotected services: DynamicService | nullget id(): string— Identifiant unique du conteneur dans le process (base 36).get closed(): boolean—trueaprèsclean— pour un scope, aprèsleaveScope.log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): ReturnType<Syslog["log"]> | void— Emit a log entry through the registeredsyslogservice.set(name: string, object: unknown): void— Register a service undername.get<T = unknown>(name: string): T | null— Resolve a service by name.remove(name: string): boolean— Unregister a service.has(name: string): boolean— Whether a service is registered undername.keys(): string[]— All service names currently registered on this container.entries(): [ string, unknown ][]— All[name, service]pairs currently registered on this container.addScope(name: string): ReadonlySet<IScope>— Declare a scope.enterScope(name: string): Scope— Open a new instance of the named scope.leaveScope(scope: IScope): void— Close a scope instance and release its services.scopeCount(name: string): number— Nombre d’instances VIVANTES du scope nommé — introspection bon marché (sondes de fuite, Studio, diagnostics) sans exposer la structure interne.removeScope(name: string): void— Close every open instance of the named scope and forget it.clean(): void— Tear the container down: close every scope and drop services.reset(): void— Clean the container and rebuild fresh prototype chains, leaving it ready to register services again.
Event#
class Event extends EventEmitter
Signatures d’abonnement d’Event : un listener peut RENDRE une valeur ou une promesse — emitAsync/emitAsyncGuarded les attendent et collectent leurs résultats. Les signatures héritées d’EventEmitter déclarent un retour void, ce qui fait passer tout listener async pour une promesse perdue ; ce contrat-ci dit la vérité. Pur type (fusion de déclarations) : aucun coût à l’exécution, les méthodes restent celles de EventEmitter.
constructor(settings?: EventDefaultInterface, context?: ContextType, options?: EventOptionInterface)settingsToListen(localSettings: EventDefaultInterface, context?: ContextType): void— ParcourtlocalSettingset enregistre chaque clé matchant/^on(.*)$/comme listener — convention héritée des composants WebComponent / config Nodefony historique.listen(context: ContextType, eventName: string | symbol, listener: Listener): (...args: unknown[]) => boolean— Bindlistenersurcontextpuis l’enregistre.fire(eventName: string | symbol, ...args: unknown[]): boolean— Aliasemit— émission synchrone (API EventEmitter standard).emitAsync(eventName: string | symbol, ...args: unknown[]): Promise<false | unknown[]>— Émet et attend chaque listener en séquence (await Reflect.applyun par un).fireAsync(eventName: string | symbol, ...args: unknown[]): Promise<false | unknown[]>— AliasemitAsync.emitAsyncGuarded(eventName: string | symbol, options?: IGuardedEmitOptions, ...args: unknown[]): Promise<IGuardedEmitResult>— Variante gardée deemitAsync: émet les listeners en SÉRIE (ordre préservé) mais isole chacun par untry/catch+ untimeoutoptionnel, et COLLECTE les échecs au lieu de laisser le premier re …
FileClass#
class FileClass
Wrapper fs Node.js avec métadonnées pré-parsées (path, name, ext, mime, stats).
stats: fs.Statstype: stringpath: fs.PathOrFileDescriptorparse: path.ParsedPathname: stringshortName: stringext: stringmimeType: string | falseencoding: stringextention: string | falsedirName: stringmatch: RegExpExecArray | nullconstructor(Path: string | fs.PathOrFileDescriptor, options?: { defer?: boolean; })static from(Path: string | fs.PathOrFileDescriptor): Promise<FileClass>— Construit un FileClass SANS I/O synchrone —fsp.lstat/fsp.realpathasync.stat(): Promise<this>— Résout les stats en async (fsp.lstat+fsp.realpath) puis hydrate l’instance.toString(): stringtoJson(): FileClassInterface— Sérialise les métadonnées du fichier en objet plain (compatible JSON.stringify).checkType(): string— Détermine le type —"File","Directory","SymbolicLink", etc.checkSum(type?: string, hasOption?: crypto.HashOptions): string— Calcule le hash du contenu du fichier (synchronous).getMimeType(name?: string): string | falsegetExtension(mimeType: string | false): string | falsegetRealpath(Path: string, options?: fs.EncodingOption): string— Canonicalise un chemin par la voie SYSTÈME (uv_fs_realpath), la même quefsp.realpathemployé par la voie async.matchName(ele: RegExp | string): boolean | RegExpExecArray | nullmatchType(type: string): booleanisFile(): booleanisDirectory(): booleanisSymbolicLink(): booleandirname(): stringisHidden(): booleancontent(encoding?: string): string | Bufferread(encoding?: string): string | Buffer— Lit le contenu du fichier (synchronous).readAsync(encoding?: string): Promise<string | Buffer>readByLine(callback: (line: string, n: number) => void, encoding?: string): string | Buffer<ArrayBufferLike>write(data: string | NodeJS.ArrayBufferView, options: fs.WriteFileOptions): void— Écrit du contenu dans le fichier (synchronous).move(target: fs.PathLike): FileClass— Déplace/renomme le fichier (synchronous).moveAsync(target: fs.PathLike): Promise<FileClass>— Déplace/renomme le fichier en async (fsp.rename) — variante non bloquante demove().unlink(): void— Supprime le fichier du filesystem (synchronous, irréversible).unlinkAsync(): Promise<void>— Supprime le fichier du filesystem en async (fsp.unlink).
Nodefony#
class Nodefony
Façade statique du framework — point d’entrée global remplaçant le singleton JS legacy.
static readonly version: string— Version du packagenodefony(lue depuispackage.jsonau build).static getKernel(): Kernel | null— Retourne leKernelcourant ounulls’il n’a pas encore été instancié.static setKernel(k: Kernel): void— Enregistre leKernelcourant — appelé une seule fois au boot.static generateId(): string— Génère un UUID v4 (aléatoire) — utilisé pourrequestId, ids divers, etc.static generateSortableId(): string— Génère un UUID v7 (RFC 9562) — identifiant ordonné dans le temps, à préférer pour une clé primaire de base de données.
Scope#
class Scope extends Container implements IScope
Short-lived child container tied to a parent Container. Used by the HTTP/WS kernel to isolate per-request services (e.g. request-bound sessions, scoped resolvers) without polluting the global container.
name: stringconstructor(name: string, parent: Container, parentProtoService: ProtoService)reset(): void— Refused on a scope: rebuilding fresh prototypes would silently detach it from its parent (every inherited service would read asnull).set(name: string, object: unknown): void— Register a per-request service — own property ONLY (shadowing).remove(name: string): boolean— Unregister a service registered ON THIS SCOPE (own property only).hasOwn(name: string): boolean—truesinameest posé SUR ce scope (propriété propre) — jamais pour un service hérité du parent.own(instance: object): void— Lie la durée de vie deinstanceà celle du scope : sonclean(), s’il en a un, sera appelé à la fermeture (Container.leaveScope), dans l’ordre INVERSE des rattachements — un service créé après ce …clean(): void— Nettoie les objets rattachés (own), du dernier au premier, puis libère le scope.
Service#
class Service implements IService
name: stringoptions: DefaultOptionsServicecontainer: Container | nullkernel: IKernel | nullsyslog: Syslog | nullget notificationsCenter(): Event— Bus d’événements du service.constructor(name: string, container?: Container, notificationsCenter?: Event | false | null, options?: DefaultOptionsService)initSyslog(environment?: EnvironmentType, debug?: DebugType, options?: conditionsInterface): ReturnType<Syslog["init"]> | null— Démarre la sortie console du Syslog avec l’environnement et la verbosité voulus.getName(): string— Renvoie le nom logique du service (utilisé commemsgidsyslog par défaut).clean(syslog?: boolean): void— Libère les ressources — retire les listeners trackés du bus partagé pour éviter les fuites mémoire, puis détache container/kernel/syslog/nc.log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message, moduleName?: string): Pdu— Émet une entrée de log structurée — point d’entrée central pour TOUT log Nodefony.logger(pci: Pci, ...args: unknown[]): void— Raccourci debug — log severityDEBUG+console.debugformaté.trace(pci: Pci, ...args: unknown[]): void— Commeloggermaisconsole.trace(avec stack trace).eventNames(): (string | symbol)[]— Liste les noms d’événements ayant au moins un listener.fire(eventName: string | symbol, ...args: unknown[]): boolean— Aliasemit— émet l’événement de manière synchrone.fireAsync(eventName: string | symbol, ...args: unknown[]): Promise<unknown>— Émet l’événement et attend que tous les listeners async résolvent.emit(eventName: string | symbol, ...args: unknown[]): boolean— Émet l’événement (API EventEmitter standard).emitAsync(eventName: string | symbol, ...args: unknown[]): Promise<unknown>— Émet et attend les listeners async — équivalent defireAsync.emitAsyncGuarded(eventName: string | symbol, options?: IGuardedEmitOptions, ...args: unknown[]): Promise<IGuardedEmitResult>— Variante gardée deemitAsync(cfEvent.emitAsyncGuarded) : isole chaque listener par try/catch + timeout et collecte les échecs.addListener(eventName: string | symbol, listener: EventListener): this— Enregistre un listener (tracké pour cleanup).listen(eventName: string | symbol, listener: EventListener): (...args: unknown[]) => boolean— Bind le listener surthispuis l’enregistre — utile quand le listener référencethis.fooet ne peut pas être tracké à l’identique.on(eventName: string | symbol, listener: EventListener): this— Enregistre un listener (tracké pour cleanup).once(eventName: string | symbol, listener: EventListener): this— Enregistre un listener one-shot — auto-retiré après le premieremit.off(eventName: string | symbol, listener: EventListener): this— Retire un listener (alias EventEmitter deremoveListener).settingsToListen(localSettings: EventDefaultInterface, context: object): void— Enregistre les événements déclarés danslocalSettings.events.listeners— utilisé en config pour mapper des hooks sans code impératif.setMaxListeners(n: number): this— Augmente la limite Node.js (défaut 10) pour éviter le warning MaxListeners.removeListener(eventName: string | symbol, listener: EventListener): this— Retire un listener spécifique et nettoie le tracking interne.removeAllListeners(eventName?: string | symbol): this— Retire tous les listeners (ou ceux d’un événement précis si fourni).prependOnceListener(eventName: string | symbol, listener: EventListener): this— Commeoncemais inséré en tête de la liste des listeners.prependListener(eventName: string | symbol, listener: EventListener): this— Commeonmais inséré en tête de la liste des listeners.getMaxListeners(): number— Limite courante de listeners avant warning Node.js.listenerCount(eventName: string | symbol, listener?: EventListener): number— Nombre de listeners attachés à un événement (filtré surlistenersi fourni).listeners(eventName: string | symbol): EventListener[]— Copie de la liste des listeners (résolus, sans le wrapperonce).rawListeners(eventName: string | symbol): EventListener[]— Commelistenersmais retourne les wrappers Node.js bruts (avec once).get<T>(name: string): T | null— Récupère un service du DI container par nom.set(name: string, obj: unknown): void— Enregistre un objet dans le DI container.remove(name: string): boolean— Retire un service du container — si c’est unService, appelle d’abord sonclean()pour libérer ses listeners.has(name: string): boolean— Vérifie l’existence d’un service dans le container.
nodefonyError#
class nodefonyError extends Error
Erreur Nodefony — wrapper riche autour de Error natif qui ajoute : - Un code numérique (HTTP status ou code custom — pas un string). - Un errorType détecté automatiquement (TypeError, SystemError, AssertionError, OrmError, ClientError, etc.). - Une sérialisation toJSON() filtrée qui exclut context, resolver, container, secure (références circulaires). - Un toString() coloré (cli-color) qui adapte le format selon l’environnement (production = message court ; dev = champs détaillés).
code: number | nullerror?: ErrorerrorType: string[key: string]: anytoJSON: () => Record<string, any>— Sérialisation JSON filtrée — POSÉE sur le prototype plus bas (Object.defineProperty(nodefonyError.prototype, "toJSON", …)), donc déclarée ici sans initialiseur (declare: aucun code émis).constructor(message?: string | Error, code?: number)static isError(error: unknown): error is Error— Type guard — vérifie qu’une valeur est une instance d’Error.static detectType(error: Error): string | false— Détecte la catégorie d’une erreur (TypeError, SystemError, OrmError, etc.).getType(error: Error): string— Détecte le type d’erreur et copie ses champs spécifiques surthis.toString(): string— Sérialise l’erreur en string coloré (cli-color) selonerrorTypeet l’environnement.parseMessage(message: unknown): void— Parse l’argument du constructeur et hydrate les champs (message,code,stack).getDefaultMessage(): void— Renseignethis.messageà partir ducodeHTTP viaSTATUS_CODES.logger(): void— Affiche l’erreur formatée surconsole.log(raccourci detoString()).
Fonctions (1)#
registerErrorAdapter#
function registerErrorAdapter(name: string, adapter: IErrorAdapter | null): void
Enregistre un adapter d’erreurs tiers sous une clé (ex. le nom du driver ORM "mongoose"). Inversion de dépendance : le module s’enregistre lui-même à son boot, le core ne connaît aucune bibliothèque. null retire l’adapter (teardown, tests).
Constantes (15)#
clc#
const clc: Clc
escapeRegExp#
const escapeRegExp: (value: string) => string
Neutralise les métacaractères d’une chaîne destinée à être insérée dans une expression régulière, pour qu’elle n’y vaille que pour elle-même.
extend#
const extend: (...args: unknown[]) => any
Fusionne plusieurs objets dans une cible — API compatible jQuery.extend.
finallyMaybe#
const finallyMaybe: <T>(step: () => MaybePromise<T>, onSettled: () => void) => MaybePromise<T>
Exécute step, puis onSettled quoi qu’il arrive — le try/finally d’une étape qui n’est asynchrone que lorsqu’elle attend.
isArray#
const isArray: (arg: any) => arg is any[]
Alias direct de Array.isArray — exporté pour usage cohérent dans les modules.
isContainer#
const isContainer: (container: unknown) => container is Container
Type guard — true si la valeur est une instance de Container (DI).
isEmptyObject#
const isEmptyObject: (obj: object | null) => boolean
Vérifie qu’un objet existe et ne contient aucune clé propre énumérable.
isFunction#
const isFunction: (value: unknown) => value is (...args: unknown[]) => unknown
Type guard — true si value est une fonction (incluant arrow et classes).
isLoopbackHostname#
const isLoopbackHostname: (hostname: string) => boolean
Ce nom d’hôte désigne-t-il la boucle locale ? Règle UNIQUE du framework — l’inspecteur de développement, le proxy inverse et le frontend décident tous par elle.
isPromise#
const isPromise: (obj: unknown) => obj is PromiseLike<unknown>
Vérifie qu’une valeur est une Promise ou un thenable (duck-typing .then).
isRegExp#
const isRegExp: (value: unknown) => value is RegExp
Type guard — true si value est une instance RegExp.
isUndefined#
const isUndefined: (value: unknown) => value is undefined
Type guard — true si value === undefined (strict, jamais null).
stripTrailingSlashes#
const stripTrailingSlashes: (value: string) => string
Retire les barres obliques finales d’une chaîne, sans expression régulière.
thenMaybe#
const thenMaybe: <T, U>(value: T | PromiseLike<T>, onResolved: (resolved: T) => MaybePromise<U>) => MaybePromise<U>
Enchaîne onResolved sur une valeur qui peut être déjà connue ou encore attendue — un .then qui reste SYNCHRONE quand il n’y a rien à attendre.
typeOf#
const typeOf: (value: unknown) => string | null
Interfaces (6)#
DynamicService#
interface DynamicService
[key: string]: unknown
IErrorAdapter#
interface IErrorAdapter
Adapter d’erreurs d’une bibliothèque tierce (driver ORM, client externe…).
isError(e: Error): boolean— Vrai si l’erreur relève de la famille gérée par cet adapter.errorToString(e: unknown): string— Formate l’erreur en message lisible.
IGuardedEmitError#
interface IGuardedEmitError
Erreur collectée pour un listener pendant Event.emitAsyncGuarded.
index: number— Index du listener fautif.error: unknown— Erreur levée par le listener (ou erreur de timeout).timedOut: boolean—truesi l’échec est un dépassement detimeoutMs.
IGuardedEmitOptions#
interface IGuardedEmitOptions
Options de Event.emitAsyncGuarded — purement MÉCANIQUES : aucune notion de module / criticité / log (ça, c’est la POLITIQUE, décidée par l’appelant via les callbacks). Sépare le « comment on isole un listener » du « quoi faire d’un échec ».
timeoutMs?: number | (listener: object, index: number) => number— Timeout par listener (ms).warnMs?: number— Seuil d’alerte de lenteur par listener (ms).onListenerError?: (error: unknown, info: IGuardedListenerInfo) => boolean | void— Appelé quand un listener rejette OU dépassetimeoutMs.onListenerSlow?: (info: IGuardedListenerInfo) => void— Appelé quand un listener réussit mais dépassewarnMs(observabilité).
IGuardedEmitResult#
interface IGuardedEmitResult
Résultat de Event.emitAsyncGuarded.
results: unknown[]— Valeurs résolues par les listeners ayant réussi (ordre d’exécution).errors: IGuardedEmitError[]— Erreurs / timeouts collectés (vide si tout a réussi).stopped: boolean—truesi la chaîne a été arrêtée paronListenerError.
IGuardedListenerInfo#
interface IGuardedListenerInfo
Information sur un listener pendant une émission gardée (Event.emitAsyncGuarded).
index: number— Index du listener dans l’ordre d’enregistrement.listener: object— Référence du listener (pour lire d’éventuels tags posés par l’appelant).timedOut: boolean—truesi le listener a été interrompu par le timeout.durationMs: number— Durée d’exécution mesurée (ms) —0si la mesure est off (warnMs ≤ 0).
Types (5)#
Clc#
type Clc = ColorFn & { readonly reset: string; }
Racine clc : une ColorFn + la constante brute reset.
ColorFn#
type ColorFn = (s: string | number) => string & { [K in StyleName]: ColorFn; }
Fonction de coloration chainable : appelable (fn(text)) et indexable (fn.bold, fn.bgBlue…), chaque accès renvoyant une nouvelle ColorFn aux styles accumulés.
MaybePromise#
type MaybePromise<T> = T | Promise<T>
Une valeur déjà connue, ou la promesse de cette valeur — le type de retour d’une étape qui n’est asynchrone que lorsqu’elle attend réellement (un corps à lire, une base, un hook qui rend une promesse).
ProtoService#
type ProtoService = { (): void; prototype: DynamicService; }
Porteur du prototype partagé des services (cf createProto).
Scopes#
type Scopes = Map<string, Set<IScope>>
Registre des scopes ouverts : nom de scope → ensemble des instances vivantes. Il ne sert qu’à les COMPTER (Container.scopeCount) et à les refermer toutes au Container.clean : un Set tenu par l’objet lui-même rend ce service sans fabriquer de clé. Un index par identifiant chaîne — fabriqué et haché à chaque ouverture — coûte ~70 % du cycle enterScope + leaveScope, payé à chaque requête.
Bibliothèques réexportées (1)#
freezeConfigTree#
Réexport sans déclaration lisible.