nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/types/Event.d.ts

@@ -0,0 +1,171 @@
+import { EventEmitter } from "node:events";
+/**
+ * Listener générique — args et retour non contraints. Volontairement basé sur
+ * `unknown` (pas `any`) : reste assignable aux signatures `EventEmitter`
+ * (`(...args: any[]) => void`) tout en forçant le narrowing côté appelant.
+ */
+type Listener = (...args: unknown[]) => unknown;
+interface EventDefaultInterface {
+    [key: string]: any;
+}
+interface EventOptionInterface {
+    nbListeners?: number;
+    [key: string]: any;
+}
+/** `this` bindé sur les listeners auto-enregistrés (non contraint). */
+type ContextType = unknown;
+/**
+ * Information sur un listener pendant une émission gardée
+ * ({@link Event.emitAsyncGuarded}).
+ */
+export interface IGuardedListenerInfo {
+    /** Index du listener dans l'ordre d'enregistrement. */
+    index: number;
+    /** Référence du listener (pour lire d'éventuels tags posés par l'appelant). */
+    listener: object;
+    /** `true` si le listener a été interrompu par le timeout. */
+    timedOut: boolean;
+    /** Durée d'exécution mesurée (ms) — `0` si la mesure est off (`warnMs ≤ 0`). */
+    durationMs: number;
+}
+/** Erreur collectée pour un listener pendant {@link Event.emitAsyncGuarded}. */
+export interface IGuardedEmitError {
+    /** Index du listener fautif. */
+    index: number;
+    /** Erreur levée par le listener (ou erreur de timeout). */
+    error: unknown;
+    /** `true` si l'échec est un dépassement de `timeoutMs`. */
+    timedOut: boolean;
+}
+/**
+ * Options de {@link 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 ».
+ */
+export interface IGuardedEmitOptions {
+    /**
+     * Timeout par listener (ms). `0` / absent = pas de timeout (0 timer alloué).
+     *
+     * Une FONCTION permet de décider listener par listener — la mécanique ne juge
+     * toujours rien, elle DEMANDE. C'est ce qui permet à un appelant d'exempter un
+     * écouteur qui n'est pas de la même nature que les autres (cf
+     * `Kernel.fireLifecycle` : l'action d'une commande n'est pas un hook de boot),
+     * sans que cette garde ait à connaître la notion de commande.
+     */
+    timeoutMs?: number | ((listener: object, index: number) => number);
+    /** Seuil d'alerte de lenteur par listener (ms). `0` / absent = 0 mesure (0 `Date.now`). */
+    warnMs?: number;
+    /**
+     * Appelé quand un listener rejette OU dépasse `timeoutMs`.
+     *
+     * @returns `true` pour **arrêter** la chaîne (les listeners suivants ne sont
+     *   pas appelés) ; toute autre valeur = on continue (fail-soft).
+     */
+    onListenerError?: (error: unknown, info: IGuardedListenerInfo) => boolean | void;
+    /** Appelé quand un listener réussit mais dépasse `warnMs` (observabilité). */
+    onListenerSlow?: (info: IGuardedListenerInfo) => void;
+}
+/** Résultat de {@link Event.emitAsyncGuarded}. */
+export interface IGuardedEmitResult {
+    /** Valeurs résolues par les listeners ayant réussi (ordre d'exécution). */
+    results: unknown[];
+    /** Erreurs / timeouts collectés (vide si tout a réussi). */
+    errors: IGuardedEmitError[];
+    /** `true` si la chaîne a été arrêtée par `onListenerError`. */
+    stopped: boolean;
+}
+/**
+ * Bus d'événements Nodefony — extension de Node.js {@link EventEmitter} avec
+ * deux ajouts maison : `emitAsync` (await tous les listeners en séquence) et
+ * `settingsToListen` (mapping config → listeners via convention `onXxx`).
+ *
+ * Utilisé par {@link Service} comme `notificationsCenter`. Une seule instance
+ * peut être partagée entre plusieurs services — chaque service track ses
+ * propres listeners pour les retirer proprement à `clean()`.
+ *
+ * @example Bus dédié
+ * ```ts
+ * const bus = new Event({ onReady: () => console.log("ready!") }, this);
+ * bus.fire("onReady");
+ * ```
+ *
+ * @example Bus partagé entre services
+ * ```ts
+ * const sharedBus = new Event();
+ * new ServiceA(name, container, sharedBus);
+ * new ServiceB(name, container, sharedBus);
+ * ```
+ */
+declare class Event extends EventEmitter {
+    /**
+     * @param settings - objet de config dont les clés `onXxx` sont auto-bindées
+     *   comme listeners (via {@link settingsToListen}).
+     * @param context - `this` à bind sur les listeners auto-enregistrés.
+     * @param options - `nbListeners` surcharge la limite d'abonnés de Node.js ;
+     *   absent, c'est celle de Node qui s'applique (10), et le dépassement
+     *   signale une fuite probable. La valeur `0` vaut **illimité**, comme dans
+     *   `setMaxListeners` — un bus dont on SAIT qu'il portera beaucoup d'abonnés
+     *   se déclare ainsi, au lieu de subir un avertissement qui n'annonce rien.
+     */
+    constructor(settings?: EventDefaultInterface, context?: ContextType, options?: EventOptionInterface);
+    /**
+     * Parcourt `localSettings` et enregistre chaque clé matchant `/^on(.*)$/`
+     * comme listener — convention héritée des composants WebComponent / config
+     * Nodefony historique. Utile pour wirer des hooks via config plate.
+     *
+     * @param localSettings - objet plat ; les clés `onReady`, `onClose`, etc.
+     *   sont prises comme noms d'événements ET comme listeners.
+     * @param context - si fourni, le listener est bindé sur ce contexte.
+     */
+    settingsToListen(localSettings: EventDefaultInterface, context?: ContextType): void;
+    /**
+     * Bind `listener` sur `context` puis l'enregistre. Renvoie une fonction
+     * dispatcher qui ré-émet l'événement avec ses propres args (façon trigger).
+     *
+     * @returns dispatcher `(...args) => this.emit(eventName, ...args)` — pratique
+     *   pour exposer un trigger sans donner accès au bus complet.
+     */
+    listen(context: ContextType, eventName: string | symbol, listener: Listener): (...args: unknown[]) => boolean;
+    /** Alias `emit` — émission synchrone (API EventEmitter standard). */
+    fire(eventName: string | symbol, ...args: unknown[]): boolean;
+    /**
+     * Émet et attend chaque listener en séquence (`await Reflect.apply` un par
+     * un). Différent de `emit` qui appelle synchroniquement sans attendre les
+     * Promises retournées.
+     *
+     * @returns tableau des valeurs résolues par chaque listener (ordre d'append),
+     *   ou `false` si aucun listener n'est attaché.
+     * @remarks Séquentiel par design — si tu veux Promise.all, fais un wrapper
+     *   au-dessus. La séquence garantit l'ordre prévisible des side-effects.
+     */
+    emitAsync(eventName: string | symbol, ...args: unknown[]): Promise<false | unknown[]>;
+    /** Alias `emitAsync`. */
+    fireAsync(eventName: string | symbol, ...args: unknown[]): Promise<false | unknown[]>;
+    /**
+     * Variante **gardée** de {@link emitAsync} : émet les listeners en SÉRIE (ordre
+     * préservé) mais isole chacun par un `try/catch` + un `timeout` optionnel, et
+     * COLLECTE les échecs au lieu de laisser le premier rejet faire sauter les
+     * suivants (ou un listener figé geler tout le reste).
+     *
+     * Ne décide d'AUCUNE politique (log, criticité, propagation) : c'est l'appelant
+     * qui tranche via `onListenerError` (continuer / arrêter) et `onListenerSlow`.
+     * Cette séparation MÉCANIQUE / POLITIQUE permet de réutiliser la garde hors boot
+     * en toute connaissance de cause.
+     *
+     * 🚨 **Coût** : quand `timeoutMs > 0`, 1 timer + 1 Promise de course PAR listener.
+     * Réservé au **boot / lifecycle / jobs** (cf `Kernel.fireLifecycle`) — appelé
+     * ≪ 1×/process. **JAMAIS dans le hot path HTTP/WS** : celui-ci garde `emitAsync`
+     * nu (aucun timer, aucune alloc par requête).
+     *
+     * @param eventName - événement à émettre.
+     * @param options - garde (timeout/seuil de lenteur) + callbacks de politique.
+     * @param args - arguments passés à chaque listener.
+     * @returns `{ results, errors, stopped }` (cf {@link IGuardedEmitResult}).
+     */
+    emitAsyncGuarded(eventName: string | symbol, options?: IGuardedEmitOptions, ...args: unknown[]): Promise<IGuardedEmitResult>;
+}
+declare const create: (settings?: EventDefaultInterface, context?: ContextType, options?: EventOptionInterface) => Event;
+declare const notification: typeof Event;
+export default Event;
+export { notification, create, EventDefaultInterface };

package/dist/types/FileClass.d.ts

@@ -0,0 +1,184 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import fs from "node:fs";
+interface FileClassInterface {
+    path: fs.PathOrFileDescriptor;
+    name: string;
+    ext: string;
+    shortName: string;
+    type: string | undefined;
+    stats: fs.Stats;
+    dirName: string;
+    parse: path.ParsedPath;
+    encoding?: string;
+    mimeType?: string | false;
+    extention?: string | false;
+}
+/**
+ * Wrapper fs Node.js avec métadonnées pré-parsées (path, name, ext, mime, stats).
+ *
+ * Utilisé par le Kernel/Module pour résoudre des chemins, par le `Finder` pour représenter
+ * un résultat de recherche, et par les Controllers HTTP pour servir des fichiers statiques.
+ *
+ * @example
+ * ```ts
+ * import { FileClass } from "nodefony";
+ * const file = new FileClass("/path/to/file.txt");
+ * file.isFile();       // true
+ * file.mimeType;       // "text/plain"
+ * const content = file.read();
+ * ```
+ *
+ * @remarks Le constructeur `new FileClass(path)` fait un `fs.lstatSync()` **synchrone**
+ *   (bloque l'event-loop) — réservé au boot/CLI. Dans **tout hot path** (requête HTTP,
+ *   Finder, upload), utiliser `await FileClass.from(path)` qui résout les stats en async
+ *   (`fsp.lstat`/`fsp.realpath`) sans bloquer la loop. Idem `moveAsync()` vs `move()`.
+ */
+declare class FileClass {
+    stats: fs.Stats;
+    type: string | undefined;
+    path: fs.PathOrFileDescriptor;
+    parse: path.ParsedPath;
+    name: string;
+    shortName: string;
+    ext: string;
+    mimeType: string | false;
+    encoding: string;
+    extention: string | false;
+    dirName: string;
+    match: RegExpExecArray | null;
+    /**
+     * Construit un FileClass à partir d'un chemin (absolu OR relatif à `process.cwd()`).
+     *
+     * Par défaut : résout `lstatSync` (suit pas les symlinks) + `realpathSync.native`, parse
+     * le path, devine le MIME type — **synchrone, bloque l'event-loop** (boot/CLI uniquement).
+     * Passer `{ defer: true }` n'effectue AUCUNE I/O (utilisé par `FileClass.from()` async).
+     *
+     * @param Path - chemin absolu OR relatif vers le fichier/dossier.
+     * @param options - `defer: true` → pas de stat au constructeur (hydrater via `stat()`).
+     * @throws Si `Path` est falsy OR si `lstatSync` échoue (fichier inexistant, hors defer).
+     */
+    constructor(Path: string | fs.PathOrFileDescriptor, options?: {
+        defer?: boolean;
+    });
+    /**
+     * Construit un FileClass SANS I/O synchrone — `fsp.lstat`/`fsp.realpath` async.
+     *
+     * À utiliser dans tout hot path (Finder, upload, render controller) pour ne PAS
+     * bloquer l'event-loop. Équivalent async de `new FileClass(path)`.
+     *
+     * @param Path - chemin absolu ou relatif à `process.cwd()`.
+     * @returns une instance hydratée (stats résolus).
+     * @throws Si `Path` est falsy ou si `lstat` échoue (inexistant).
+     */
+    static from(Path: string | fs.PathOrFileDescriptor): Promise<FileClass>;
+    /**
+     * Résout les stats en async (`fsp.lstat` + `fsp.realpath`) puis hydrate l'instance.
+     * Aucune I/O synchrone. Appelé par `FileClass.from()` ; rappelable pour rafraîchir.
+     *
+     * @returns `this` (chaînable, type polymorphe pour les sous-classes type `File`).
+     */
+    stat(): Promise<this>;
+    /**
+     * Renseigne stats/type/path/parse/name/mime à partir de stats déjà résolus.
+     * Partagé par le constructeur sync et `stat()` async — **aucune I/O ici** (pur).
+     *
+     * @param stats - résultat d'un `lstat` (sync ou async).
+     * @param resolvedPath - path réel (realpath) ou path original si symlink.
+     */
+    private hydrate;
+    /**
+     * @returns le path absolu (utile pour les concat string).
+     */
+    toString(): string;
+    /**
+     * Sérialise les métadonnées du fichier en objet plain (compatible JSON.stringify).
+     *
+     * @returns objet contenant path, name, ext, stats, mime, etc.
+     */
+    toJson(): FileClassInterface;
+    /**
+     * Détermine le type — `"File"`, `"Directory"`, `"SymbolicLink"`, etc.
+     *
+     * @returns nom du type ou `undefined` si stats indéterminé.
+     */
+    checkType(): string | undefined;
+    /**
+     * Calcule le hash du contenu du fichier (synchronous).
+     *
+     * @param type - algorithme (`"md5"` défaut, `"sha1"`, `"sha256"`, etc.).
+     * @param hasOption - options crypto.HashOptions.
+     * @returns hash hexadécimal.
+     */
+    checkSum(type?: string, hasOption?: crypto.HashOptions): string;
+    getMimeType(name?: string): string | false;
+    getExtension(mimeType: string | false): string | false;
+    /**
+     * Canonicalise un chemin par la voie SYSTÈME (`uv_fs_realpath`), la même que
+     * `fsp.realpath` employé par la voie async.
+     *
+     * @remarks `fs.realpathSync` (sans `.native`) est une implémentation JavaScript qui
+     *   se contente de dérouler les liens : sous Windows elle **conserve les noms courts
+     *   8.3** (`C:\Users\RUNNER~1\…`) là où la voie système rend la forme longue
+     *   (`C:\Users\runneradmin\…`). Deux canonicalisations pour un même fichier, donc
+     *   deux `path` différents selon qu'on est passé par le constructeur ou par
+     *   `FileClass.from()` — et toute comparaison de chemins (dédup, cache, garde
+     *   « la cible reste-t-elle sous le dossier autorisé ? ») devient fausse sans un mot.
+     *   Sous POSIX les deux voies sont identiques : l'alignement ne change rien.
+     *
+     * @param Path - chemin à canonicaliser.
+     * @param options - encodage (cf `fs.EncodingOption`).
+     * @returns le chemin réel, forme canonique du système de fichiers.
+     */
+    getRealpath(Path: string, options?: fs.EncodingOption): string;
+    matchName(ele: RegExp | string): boolean | RegExpExecArray | null;
+    matchType(type: string): boolean;
+    /** @returns `true` si le path pointe vers un fichier régulier. */
+    isFile(): boolean;
+    /** @returns `true` si le path pointe vers un dossier. */
+    isDirectory(): boolean;
+    /** @returns `true` si le path est un lien symbolique. */
+    isSymbolicLink(): boolean;
+    dirname(): string;
+    /** @returns `true` si le nom commence par `.` (fichier caché Unix). */
+    isHidden(): boolean;
+    content(encoding?: string): string | Buffer;
+    /**
+     * Lit le contenu du fichier (synchronous).
+     *
+     * @param encoding - encoding (défaut `"utf8"`). Si non fourni → retourne Buffer.
+     * @returns contenu sous forme de string OR Buffer.
+     */
+    read(encoding?: string): string | Buffer;
+    readAsync(encoding?: string): Promise<string | Buffer>;
+    readByLine(callback: (line: string, n: number) => void, encoding?: string): string | Buffer<ArrayBufferLike>;
+    /**
+     * Écrit du contenu dans le fichier (synchronous).
+     *
+     * @param data - contenu à écrire (string OR Buffer).
+     * @param options - options fs.write (encoding, flags).
+     * @returns this (chaînable).
+     */
+    write(data: string | NodeJS.ArrayBufferView, options: fs.WriteFileOptions): void;
+    /**
+     * Déplace/renomme le fichier (synchronous).
+     *
+     * @param target - chemin de destination.
+     * @returns nouvelle instance FileClass pointant vers `target`.
+     */
+    move(target: fs.PathLike): FileClass;
+    /**
+     * Déplace/renomme le fichier en **async** (`fsp.rename`) — variante non bloquante
+     * de `move()`. À préférer dans le pipeline (upload, controller).
+     *
+     * @param target - chemin de destination.
+     * @returns nouvelle instance FileClass (hydratée async) sur `target`.
+     */
+    moveAsync(target: fs.PathLike): Promise<FileClass>;
+    /** Supprime le fichier du filesystem (synchronous, irréversible). */
+    unlink(): void;
+    /** Supprime le fichier du filesystem en **async** (`fsp.unlink`). */
+    unlinkAsync(): Promise<void>;
+}
+export default FileClass;
+export { FileClassInterface };

package/dist/types/Nodefony.d.ts

@@ -0,0 +1,66 @@
+import type Kernel from "./kernel/Kernel.js";
+/**
+ * Façade statique du framework — point d'entrée global remplaçant le singleton JS legacy.
+ *
+ * Expose le `Kernel` courant (registre des modules + services), la version du
+ * package, et des générateurs d'identifiants UUID. Constructeur privé — aucune
+ * instance ne doit être créée ; tout passe par les statics.
+ *
+ * @example
+ * ```ts
+ * import { Nodefony } from "nodefony";
+ * const kernel = Nodefony.getKernel();
+ * const id = Nodefony.generateId();
+ * ```
+ *
+ * @remarks Le `Kernel` est `null` tant qu'il n'a pas été instancié par
+ *   `bin/nodefony` ou par un test — toujours tester avec `?.`.
+ */
+export declare class Nodefony {
+    #private;
+    /** Version du package `nodefony` (lue depuis `package.json` au build). */
+    static readonly version: string;
+    private constructor();
+    /**
+     * Retourne le `Kernel` courant ou `null` s'il n'a pas encore été instancié.
+     *
+     * @returns instance unique du Kernel ou `null` (avant boot ou après shutdown).
+     */
+    static getKernel(): Kernel | null;
+    /**
+     * Enregistre le `Kernel` courant — appelé une seule fois au boot.
+     *
+     * @param k - instance du Kernel à mémoriser.
+     * @remarks Appels multiples écrasent la référence précédente sans warning.
+     */
+    static setKernel(k: Kernel): void;
+    /**
+     * Génère un UUID v4 (aléatoire) — utilisé pour `requestId`, ids divers, etc.
+     * Natif `node:crypto` (CSPRNG) — plus de dépendance `uuid`.
+     *
+     * @returns string UUID format `8-4-4-4-12`.
+     */
+    static generateId(): 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.
+     *
+     * Pourquoi lui plutôt que {@link generateId} (v4) sur une clé primaire : les 48
+     * premiers bits portent l'horodatage, donc les lignes insérées à la suite
+     * atterrissent **côte à côte dans l'index** ; un UUID v4, purement aléatoire,
+     * fragmente le B-tree à chaque insertion. Et contrairement à un auto-incrément,
+     * il ne donne pas l'énumération de toutes les ressources.
+     *
+     * ⚠️ **Deux limites à connaître.**
+     * 1. **Pas d'ordre garanti dans une même milliseconde** : Node n'implémente pas le
+     *    compteur monotone optionnel de la RFC (§6.2) — mesuré : ~50 % d'inversions
+     *    entre identifiants tirés dans la même milliseconde. Trier des créations se
+     *    fait sur `createdAt`, **jamais** sur l'identifiant.
+     * 2. **Pas un secret** : la RFC l'interdit explicitement comme capacité de sécurité
+     *    (« MUST NOT be used as security capabilities ») — l'instant de création fuit et
+     *    une partie est devinable. Pour un jeton imprévisible → {@link generateId} (v4).
+     *
+     * @returns UUID v7, format `8-4-4-4-12`.
+     */
+    static generateSortableId(): string;
+}

package/dist/types/Service.d.ts

@@ -0,0 +1,165 @@
+import { DebugType, EnvironmentType } from "./types/globals.js";
+import type { IService, DefaultOptionsService, EventListener } from "./types/IService.js";
+import type { IKernel } from "./types/IKernel.js";
+import Container, { DynamicParam } from "./Container.js";
+import Event, { EventDefaultInterface } from "./Event.js";
+import type { IGuardedEmitOptions, IGuardedEmitResult } from "./Event.js";
+import Pdu, { Severity, Msgid, Message, Pci } from "./syslog/Pdu.js";
+import Syslog, { conditionsInterface } from "./syslog/Syslog.js";
+/**
+ * Brique de base de tout composant Nodefony — câble un nom, un {@link Container} DI,
+ * un {@link Syslog} et un bus d'événements {@link Event} (notificationsCenter).
+ *
+ * Tous les services, modules, kernels et controllers héritent de cette classe.
+ * Délègue son API EventEmitter à `notificationsCenter` et son API DI au `container`.
+ *
+ * Cycle de vie attendu :
+ * - `new Service(name, container?, nc?, options?)` — initialise les dépendances
+ * - `initSyslog(env, debug, options?)` — démarre la sortie console (optionnel)
+ * - `clean()` — retire les listeners trackés et libère les références
+ *
+ * @remarks Si `notificationsCenter === false`, le service est créé sans bus
+ *   d'événements — utile pour des services purement utilitaires.
+ */
+declare class Service implements IService {
+    #private;
+    name: string;
+    options: DefaultOptionsService;
+    container: Container | null;
+    kernel: IKernel | null;
+    syslog: Syslog | null;
+    get notificationsCenter(): Event | undefined;
+    private get nc();
+    /**
+     * Initialise le service — réutilise les ressources du conteneur si possible,
+     * sinon les crée à la volée.
+     *
+     * @param name - identifiant logique du service (apparaît dans les logs comme `msgid`).
+     * @param container - {@link Container} DI partagé ; sinon un nouveau est instancié.
+     * @param notificationsCenter - {@link Event} bus existant à partager, ou `false`
+     *   pour désactiver les events, ou `null`/`undefined` pour créer un bus dédié.
+     * @param options - surcharge des défauts (`events.nbListeners`, `syslog.moduleName`…).
+     */
+    constructor(name: string, container?: Container, notificationsCenter?: Event | false | null, options?: DefaultOptionsService);
+    /**
+     * Convention `onXxx` → enregistre les listeners déclarés en config (clé
+     * matchant `/^on(.+)$/`) via {@link Service.on} pour que {@link clean}
+     * puisse les retirer du bus partagé. Variante trackée de
+     * {@link Event.settingsToListen}.
+     */
+    private attachConfiguredListeners;
+    /**
+     * Démarre la sortie console du Syslog avec l'environnement et la verbosité voulus.
+     *
+     * @param environment - `"production"` (défaut) ou `"development"`.
+     * @param debug - flag de verbosité (true ou {@link DebugType}).
+     * @param options - {@link conditionsInterface} pour filtrer les Pdu (severity, msgid…).
+     * @returns le résultat de {@link Syslog.init} ou `null` si pas de Syslog.
+     */
+    initSyslog(environment?: EnvironmentType, debug?: DebugType, options?: conditionsInterface): ReturnType<Syslog["init"]> | null;
+    /** Renvoie le nom logique du service (utilisé comme `msgid` syslog par défaut). */
+    getName(): string;
+    /**
+     * 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.
+     *
+     * @param syslog - si `true`, appelle aussi {@link Syslog.reset} (transports fermés).
+     * @remarks Après `clean()`, toute API héritée (log, event, container) lèvera une erreur.
+     */
+    clean(syslog?: boolean): void;
+    /**
+     * Émet une entrée de log structurée — point d'entrée central pour TOUT log Nodefony.
+     *
+     * @param pci - charge utile (string, objet, Error…). Stockée dans {@link Pdu.payload}.
+     * @param severity - niveau syslog (`INFO`, `WARNING`, `ERROR`, `CRITIC`, `DEBUG`…).
+     * @param msgid - identifiant logique ; défaut = `this.name`.
+     * @param msg - message libre additionnel.
+     * @returns le {@link Pdu} émis (utile pour chaîner des transports).
+     * @remarks Si syslog est down, fabrique un Pdu directement et catch toute exception.
+     */
+    log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): Pdu;
+    /** Raccourci debug — log severity `DEBUG` + `console.debug` formaté. */
+    logger(pci: Pci, ...args: unknown[]): void;
+    /** Comme {@link logger} mais `console.trace` (avec stack trace). */
+    trace(pci: Pci, ...args: unknown[]): void;
+    private trackListener;
+    private untrackListener;
+    /** Liste les noms d'événements ayant au moins un listener. */
+    eventNames(): (string | symbol)[];
+    /** Alias `emit` — émet l'événement de manière synchrone. */
+    fire(eventName: string | symbol, ...args: unknown[]): boolean;
+    /** Émet l'événement et attend que tous les listeners async résolvent. */
+    fireAsync(eventName: string | symbol, ...args: unknown[]): Promise<unknown>;
+    /** Émet l'événement (API EventEmitter standard). */
+    emit(eventName: string | symbol, ...args: unknown[]): boolean;
+    /** Émet et attend les listeners async — équivalent de {@link fireAsync}. */
+    emitAsync(eventName: string | symbol, ...args: unknown[]): Promise<unknown>;
+    /**
+     * Variante **gardée** de {@link emitAsync} (cf `Event.emitAsyncGuarded`) : isole
+     * chaque listener par try/catch + timeout et collecte les échecs. Réservé au
+     * **boot / lifecycle / jobs** (cf `Kernel.fireLifecycle`) — JAMAIS le hot path.
+     */
+    emitAsyncGuarded(eventName: string | symbol, options?: IGuardedEmitOptions, ...args: unknown[]): Promise<IGuardedEmitResult>;
+    /** Enregistre un listener (tracké pour cleanup). Voir aussi {@link on}. */
+    addListener(eventName: string | symbol, listener: EventListener): this;
+    /**
+     * Bind le listener sur `this` puis l'enregistre — utile quand le listener
+     * référence `this.foo` et ne peut pas être tracké à l'identique.
+     *
+     * @returns le listener wrappé (ne PAS passer le listener original à `off()`).
+     */
+    listen(eventName: string | symbol, listener: EventListener): (...args: unknown[]) => boolean;
+    /** Enregistre un listener (tracké pour cleanup). Alias EventEmitter de {@link addListener}. */
+    on(eventName: string | symbol, listener: EventListener): this;
+    /** Enregistre un listener one-shot — auto-retiré après le premier `emit`. */
+    once(eventName: string | symbol, listener: EventListener): this;
+    /** Retire un listener (alias EventEmitter de {@link removeListener}). */
+    off(eventName: string | symbol, listener: EventListener): this;
+    /**
+     * Enregistre les événements déclarés dans `localSettings.events.listeners`
+     * — utilisé en config pour mapper des hooks sans code impératif.
+     */
+    settingsToListen(localSettings: EventDefaultInterface, context: object): void;
+    /** Augmente la limite Node.js (défaut 10) pour éviter le warning MaxListeners. */
+    setMaxListeners(n: number): this;
+    /** Retire un listener spécifique et nettoie le tracking interne. */
+    removeListener(eventName: string | symbol, listener: EventListener): this;
+    /** Retire tous les listeners (ou ceux d'un événement précis si fourni). */
+    removeAllListeners(eventName?: string | symbol): this;
+    /** Comme {@link once} mais inséré en tête de la liste des listeners. */
+    prependOnceListener(eventName: string | symbol, listener: EventListener): this;
+    /** Comme {@link on} mais inséré en tête de la liste des listeners. */
+    prependListener(eventName: string | symbol, listener: EventListener): this;
+    /** Limite courante de listeners avant warning Node.js. */
+    getMaxListeners(): number;
+    /** Nombre de listeners attachés à un événement (filtré sur `listener` si fourni). */
+    listenerCount(eventName: string | symbol, listener?: EventListener): number;
+    /** Copie de la liste des listeners (résolus, sans le wrapper `once`). */
+    listeners(eventName: string | symbol): EventListener[];
+    /** Comme {@link listeners} mais retourne les wrappers Node.js bruts (avec once). */
+    rawListeners(eventName: string | symbol): EventListener[];
+    /** Récupère un service du DI container par nom. Retourne `null` si absent ou clean(). */
+    get<T>(name: string): T | null;
+    /**
+     * Enregistre un objet dans le DI container.
+     * @throws Error si `clean()` a déjà détaché le container.
+     */
+    set<T>(name: string, obj: T): void;
+    /**
+     * Retire un service du container — si c'est un `Service`, appelle d'abord
+     * son `clean()` pour libérer ses listeners.
+     * @returns `true` si retiré, `false` si introuvable ou container détaché.
+     */
+    remove(name: string): boolean;
+    /** Récupère un paramètre dynamique (config résolue) — `null` si absent. */
+    getParameters(name: string): DynamicParam | null;
+    /**
+     * Définit un paramètre dynamique dans le container.
+     * @throws Error si `clean()` a déjà détaché le container.
+     */
+    setParameters<T>(name: string, ele: T): DynamicParam | null;
+    /** Vérifie l'existence d'un service ou paramètre dans le container. */
+    has(name: string): boolean;
+}
+export default Service;
+export type { IService, IKernel, DefaultOptionsService, EventListener };