nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/client/syslog/drivers/pduFlow.js

@@ -0,0 +1,106 @@
+//#region src/syslog/drivers/pduFlow.ts
+/**
+* Table des étapes — **source unique** de l'ordre et de l'appartenance protocole,
+* partagée back (filtre) et front (sélecteur groupé HTTP / WebSocket / Commun).
+*/
+const FLOW_STEPS = {
+	"request-in": {
+		order: 1,
+		protocol: "http"
+	},
+	"body-received": {
+		order: 2,
+		protocol: "http"
+	},
+	"route-matched": {
+		order: 3,
+		protocol: "http"
+	},
+	"kernel-dispatch": {
+		order: 4,
+		protocol: "http"
+	},
+	session: {
+		order: 5,
+		protocol: "both"
+	},
+	response: {
+		order: 6,
+		protocol: "http"
+	},
+	"session-saved": {
+		order: 7,
+		protocol: "both"
+	},
+	"request-end": {
+		order: 8,
+		protocol: "http"
+	},
+	finish: {
+		order: 9,
+		protocol: "http"
+	},
+	"ws-open": {
+		order: 1,
+		protocol: "ws"
+	},
+	"ws-message": {
+		order: 2,
+		protocol: "ws"
+	},
+	"ws-close": {
+		order: 3,
+		protocol: "ws"
+	}
+};
+/** Retire les codes de couleur ANSI (les payloads en TTY peuvent en porter). */
+function stripAnsi(s) {
+	return s.replace(/\x1b\[[0-9;]*m/g, "");
+}
+/** Texte indexable d'un Pdu pour la classification (payload string sinon `msg`). */
+function flowText(pdu) {
+	return stripAnsi(typeof pdu.payload === "string" ? pdu.payload : pdu.msg || "");
+}
+/**
+* Classe un Pdu en **étape de cycle de vie** (id stable) ou `null` si la ligne
+* n'est pas un jalon (log applicatif libre, ex. `DB-DEMO`). PUR, isomorphe,
+* 0 état — réutilisé par le filtre back ({@link filterPdus}) ET le rendu front
+* (colonne « Étape » + sélecteur) → une SEULE logique, jamais de divergence.
+*
+* Priorité aux marqueurs de **contenu** (route, session, cookie, bilan), puis au
+* **nom d'event** générique. `onRequest` est désambiguïsé par le msgid `KERNEL`
+* (dispatch kernel) vs contexte (entrée de requête).
+*
+* @param pdu - enregistrement (Pdu ou {@link IPduLike}, relu d'un JSONL aussi).
+* @returns l'`id` d'étape, ou `null` pour un log hors cycle.
+*/
+function pduFlowStep(pdu) {
+	const msg = flowText(pdu);
+	if (/Match route/i.test(msg)) return "route-matched";
+	if (/NEW SESSION|MIGRATE SESSION|DESTROY SESSION|SESSION CONTEXT CHANGE/i.test(msg)) return "session";
+	if (/SAVE SESSION/i.test(msg)) return "session-saved";
+	if (/ADD COOKIE/i.test(msg)) return "response";
+	if (/\bsubscribe\b/i.test(msg)) return "ws-message";
+	if (/client connected/i.test(msg)) return "ws-open";
+	if (/^WS (RECEIVE|SEND|BROADCAST)\b/.test(pdu.msgid)) return "ws-message";
+	if (pdu.msgid === "req") return "request-end";
+	const m = msg.match(/\bon([A-Z][A-Za-z]+)\b/);
+	if (m) {
+		const ev = `on${m[1]}`;
+		if (ev === "onRequest" && pdu.msgid === "KERNEL") return "kernel-dispatch";
+		switch (ev) {
+			case "onRequestEnd": return "body-received";
+			case "onRequest": return "request-in";
+			case "onSessionStart": return "session";
+			case "onConnect": return "ws-open";
+			case "onSaveSession": return "session-saved";
+			case "onSend": return "response";
+			case "onClose": return "ws-close";
+			case "onFinish": return "finish";
+			case "onMessage": return "ws-message";
+		}
+	}
+	return null;
+}
+//#endregion
+export { FLOW_STEPS, pduFlowStep };

package/dist/client/syslog/drivers/pduProtocol.js

@@ -0,0 +1,28 @@
+//#region src/syslog/drivers/pduProtocol.ts
+/**
+* msgid forcé par défaut sur **tout** log émis dans un contexte WebSocket
+* (`WebsocketContext.log()` côté `@nodefony/http`). C'est le marqueur fiable du
+* protocole — pas de parsing de message.
+*/
+const WS_MSGID = "WEBSOCKET CONTEXT";
+/**
+* Classe un Pdu par **protocole** d'origine — `"ws"` ou `"http"` — de façon PURE,
+* isomorphe et 0-alloc (une seule comparaison de `msgid`).
+*
+* Critère FIABLE : tout log émis dans un contexte WebSocket porte le msgid
+* `"WEBSOCKET CONTEXT"` (forcé par défaut dans `WebsocketContext.log()`). Tout le
+* reste du pipeline (req/http2/router/firewall/kernel/applicatif) est classé HTTP.
+* Une seule logique → front et back ne divergent plus (le front filtrait par texte,
+* source de faux positifs).
+*
+* Seul `msgid` compte → accepte un `Pdu`, un {@link IPduLike} ou un record wire
+* relu (`ILogRecord` / miroir front) indifféremment.
+*
+* @param pdu - tout objet portant un `msgid`.
+* @returns `"ws"` si le log provient d'une socket WebSocket, sinon `"http"`.
+*/
+function pduProtocol(pdu) {
+	return pdu.msgid === WS_MSGID ? "ws" : "http";
+}
+//#endregion
+export { pduProtocol };

package/dist/client/syslog/logColor.js

@@ -0,0 +1,80 @@
+import clc from "../colors.js";
+//#region src/syslog/logColor.ts
+/** Combinaisons `cli-color` réellement utilisées par les loggers Nodefony. */
+const KEYS = [
+	"cyan",
+	"magenta",
+	"red",
+	"green",
+	"yellow",
+	"blue",
+	"blackBright",
+	"yellowBold",
+	"redBold",
+	"cyanBold",
+	"blueBrightBold",
+	"cyanBgBlue",
+	"cyanBgBlack"
+];
+const identity = (s) => s;
+/** Implémentation colorée (TTY) — résolue 1× à l'import (chaînage figé). */
+const COLORS = {
+	cyan: clc.cyan,
+	magenta: clc.magenta,
+	red: clc.red,
+	green: clc.green,
+	yellow: clc.yellow,
+	blue: clc.blue,
+	blackBright: clc.blackBright,
+	yellowBold: clc.yellow.bold,
+	redBold: clc.red.bold,
+	cyanBold: clc.cyan.bold,
+	blueBrightBold: clc.blueBright.bold,
+	cyanBgBlue: clc.cyan.bgBlue,
+	cyanBgBlack: clc.cyan.bgBlack
+};
+/**
+* Helper de couleur partagé — référence STABLE, propriétés mutées par
+* {@link setLogColor}. Les call-sites font `logColor.cyan("URL")`.
+*/
+const logColor = { ...COLORS };
+let _enabled = false;
+/**
+* Active/désactive la couleur ANSI des logs — à appeler **une fois au boot**.
+* Swap les fonctions des slots ; aucun coût par log ensuite.
+*
+* @param enabled - `true` = couleur (TTY interactif), `false` = brut (pipe/fichier).
+*/
+function setLogColor(enabled) {
+	_enabled = enabled;
+	for (const k of KEYS) logColor[k] = enabled ? COLORS[k] : identity;
+}
+/** `true` si la couleur ANSI est active (gate boot-time). */
+function isLogColorEnabled() {
+	return _enabled;
+}
+/**
+* Applique les conventions d'environnement couleur PAR-DESSUS un signal `isTTY`
+* **déjà résolu** — au boot on passe `Kernel.isTTY` (qui honore déjà `NF_NO_TTY`),
+* sans re-lire `process.stdout`. Conventions :
+*
+* - **`NO_COLOR`** (no-color.org) : présent **et non vide** → couleur OFF, quelle
+*   que soit sa valeur. Priorité absolue (refus explicite de l'utilisateur).
+* - **`FORCE_COLOR`** : non vide et ≠ `"0"` → couleur ON (override pipe/non-TTY,
+*   ex. CI qui veut des logs colorés capturés).
+* - sinon → couleur = `isTTY`.
+*
+* Isomorphe : `env` lu via `globalThis.process` (navigateur : pas de `process`).
+*
+* @param isTTY - signal TTY déjà résolu (ex. `Kernel.isTTY`, NF_NO_TTY-aware).
+*/
+function resolveColorEnabled(isTTY) {
+	const env = globalThis.process?.env ?? {};
+	if (typeof env.NO_COLOR === "string" && env.NO_COLOR !== "") return false;
+	if (typeof env.FORCE_COLOR === "string" && env.FORCE_COLOR !== "" && env.FORCE_COLOR !== "0") return true;
+	return isTTY;
+}
+const _importProc = globalThis.process;
+setLogColor(resolveColorEnabled(_importProc?.env?.NF_NO_TTY ? false : _importProc?.stdout?.isTTY === true));
+//#endregion
+export { isLogColorEnabled, logColor, resolveColorEnabled, setLogColor };

package/dist/client/types/src/Container.d.ts

@@ -0,0 +1,221 @@
+import type { Message, Msgid, Pci, Severity } from "./syslog/Pdu.js";
+import Syslog from "./syslog/Syslog.js";
+import type { IContainer, IScope } from "./types/IContainer.js";
+export interface DynamicService {
+    [key: string]: unknown;
+}
+export interface DynamicParam {
+    [key: string]: unknown;
+}
+/**
+ * Bookkeeping des scopes ouverts : nom de scope → instances vivantes par id.
+ * `Map` (et plus un objet `delete`-é) : l'ajout/retrait a lieu à CHAQUE
+ * requête — le churn de shape d'un objet ordinaire dégrade les inline caches
+ * V8, la Map est conçue pour ce motif.
+ */
+export type Scopes = Map<string, Map<string, Scope>>;
+export type ProtoService = {
+    (): void;
+    [key: string]: any;
+};
+export type ProtoParameters = {
+    (): void;
+    [key: string]: any;
+};
+/**
+ * Dependency Injection container — registers services by name and exposes
+ * them to the rest of the framework.
+ *
+ * Services are stored on a prototype-backed object (`protoService`) so they
+ * are inherited by child scopes (see {@link Scope}). The container also
+ * carries an arbitrary parameter tree (`parameters`) used for configuration.
+ *
+ * Conventional usage:
+ * ```ts
+ * const c = new Container();
+ * c.set("logger", new LoggerService());
+ * c.setParameters("kernel.environment", "development");
+ * const logger = c.get<LoggerService>("logger");
+ * ```
+ *
+ * See `src/nodefony/docs/container.md` for the high-level rationale and the
+ * scope model used by the HTTP/WS request pipeline.
+ */
+declare class Container implements IContainer {
+    protoService: ProtoService;
+    protected services: DynamicService | null;
+    protoParameters: ProtoParameters;
+    protected parameters: DynamicParam | null;
+    id: string;
+    private scopes;
+    private setServices;
+    private setParametersBulk;
+    /**
+     * Emit a log entry through the registered `syslog` service. Falls back to
+     * `console.warn` when no syslog is set (early boot, isolated test).
+     *
+     * @param pci - log payload (string or structured PDU body)
+     * @param severity - syslog severity level
+     * @param msgid - message id; defaults to `"SERVICES CONTAINER"`
+     * @param msg - optional message detail
+     */
+    log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): ReturnType<Syslog["log"]> | void;
+    /**
+     * Register a service under `name`. The service is stored both directly on
+     * the container and on its prototype, so child scopes can read it without
+     * an extra hop.
+     *
+     * @param name - service identifier (any non-empty string)
+     * @param object - the instance to register (no type constraint — services
+     * are not required to extend any base class)
+     * @throws Error if `name` is empty or the container has been cleaned
+     */
+    set<T>(name: string, object: T): void;
+    /**
+     * Resolve a service by name. Returns `null` if the service is unknown or
+     * the container has been cleaned — callers should narrow the result
+     * before use.
+     *
+     * @param name - service identifier
+     * @returns the service instance typed as `T`, or `null`
+     */
+    get<T = unknown>(name: string): T | null;
+    /**
+     * Unregister a service and cascade the removal into every child scope.
+     *
+     * @param name - service identifier
+     * @returns `true` when a service was actually removed, `false` otherwise
+     */
+    remove(name: string): boolean;
+    /** Whether a service is registered under `name`. */
+    has(name: string): boolean;
+    /** All service names currently registered on this container. */
+    keys(): string[];
+    /** All `[name, service]` pairs currently registered on this container. */
+    entries(): [string, unknown][];
+    /**
+     * Declare a scope. Scopes are short-lived containers (typically created
+     * per HTTP/WS request) that inherit services from this container but
+     * store their own per-request services and parameters. Must be called
+     * once before {@link enterScope} can produce instances.
+     *
+     * @param name - scope identifier (e.g. `"request"`)
+     * @returns the underlying scope bucket (rarely used by callers)
+     */
+    addScope(name: string): Map<string, Scope>;
+    /**
+     * Open a new instance of the named scope. The returned {@link Scope}
+     * inherits services from this container but tracks its own services and
+     * parameters in isolation.
+     *
+     * @param name - scope name previously declared via {@link addScope}
+     * @returns a fresh `Scope` instance with a unique `id`
+     * @throws Error when the scope has not been declared
+     */
+    enterScope(name: string): Scope;
+    /**
+     * Close a scope instance and release its services/parameters. Always
+     * called when the unit of work that opened the scope finishes (request
+     * end, WS close).
+     *
+     * @param scope - the scope instance returned by {@link enterScope}
+     */
+    leaveScope(scope: IScope): void;
+    /**
+     * Nombre d'instances VIVANTES du scope nommé — introspection bon marché
+     * (sondes de fuite, Studio, diagnostics) sans exposer la structure interne.
+     *
+     * @param name - scope identifier (e.g. `"request"`)
+     * @returns le nombre de scopes ouverts, `0` si le scope est inconnu
+     */
+    scopeCount(name: string): number;
+    /**
+     * Close every open instance of the named scope and forget it. After this
+     * call, {@link enterScope}(`name`) will throw until {@link addScope} is
+     * called again.
+     *
+     * @param name - scope identifier
+     */
+    removeScope(name: string): void;
+    private removeAllScopes;
+    /**
+     * Set a value in the parameter tree using a dotted path. Intermediate
+     * objects are created on demand (`a.b.c = 1` creates `a` and `b` if they
+     * are missing).
+     *
+     * @param name - dotted path (e.g. `"kernel.environment"`)
+     * @param ele - value to assign (must not be `undefined`)
+     * @returns the parameter subtree containing the assigned value, or `null`
+     * if the container has been cleaned
+     * @throws Error when `name` is not a string or `ele` is `undefined`
+     */
+    setParameters<T>(name: string, ele: T): DynamicParam | null;
+    /**
+     * Read a value (or subtree) from the parameter tree.
+     *
+     * @param name - dotted path (e.g. `"kernel.environment"`)
+     * @returns the value, the subtree, or `null` if absent
+     * @throws Error when `name` is empty
+     */
+    getParameters(name: string): DynamicParam | null;
+    /**
+     * Tear the container down: close every scope, drop services and
+     * parameters. After `clean()`, any `get`/`set`/`enterScope` call on this
+     * instance throws or returns `null`. Called by the kernel during
+     * graceful shutdown.
+     */
+    clean(): void;
+    /**
+     * Clean the container and rebuild fresh prototype chains, leaving it
+     * ready to register services again. Used by hot-reload paths in tests
+     * and dev mode; production code rarely calls this directly.
+     */
+    reset(): void;
+}
+/**
+ * Short-lived child container tied to a parent {@link Container}. Used by
+ * the HTTP/WS kernel to isolate per-request services (e.g. request-bound
+ * sessions, scoped resolvers) without polluting the global container.
+ *
+ * Services and parameters defined on a `Scope` shadow the parent's — reads
+ * fall back to the parent transparently when nothing is found locally.
+ */
+declare class Scope extends Container implements IScope {
+    name: string;
+    private parent;
+    constructor(name: string, parent: Container, parentProtoService: ProtoService, parentProtoParameters: ProtoParameters);
+    /**
+     * Register a per-request service — own property ONLY (shadowing). Depuis
+     * l'adoption des protos parents, l'écriture prototype de
+     * {@link Container.set} toucherait le proto PARTAGÉ du parent : un service
+     * per-request (controller, context) deviendrait visible de TOUTES les
+     * requêtes concurrentes. (L'ancien chemin écrivait sur un proto local mort
+     * — travail perdu à chaque set.)
+     */
+    set<T>(name: string, object: T): void;
+    /**
+     * Unregister a service registered ON THIS SCOPE (own property only). Les
+     * services hérités du parent ne sont jamais touchés — même raison que
+     * {@link Scope.set} : le proto est partagé depuis l'adoption.
+     */
+    remove(name: string): boolean;
+    /**
+     * Read a parameter from the scope, falling back to the parent container.
+     * When both sides hold plain objects, the result is a merged view (deep
+     * by default) so a scope can override a few keys without losing the rest.
+     *
+     * @param name - dotted path
+     * @param merge - when `true` (default), merge scope and parent objects;
+     * when `false`, scope value wins outright if present
+     * @param deep - deep vs. shallow merge (only when `merge` is `true`)
+     */
+    getParameters(name: string, merge?: boolean, deep?: boolean): DynamicParam | null;
+    /**
+     * Break the parent link and clean the scope. Called by
+     * {@link Container.leaveScope} when the unit of work that owns the scope
+     * finishes.
+     */
+    clean(): void;
+}
+export default Container;
+export { Scope };

package/dist/client/types/src/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 };