nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/Event.js

@@ -0,0 +1,198 @@
+import { EventEmitter } from "node:events";
+//#region src/Event.ts
+const regListenOn = /^on(.*)$/;
+/** Sentinelle de rejet interne au timeout d'{@link Event.emitAsyncGuarded} (jamais exposée). */
+const timeoutSentinel = Symbol("nodefony.emitAsyncGuarded.timeout");
+/**
+* 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);
+* ```
+*/
+var Event = class 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, context, options) {
+		super();
+		if (options?.nbListeners !== void 0) this.setMaxListeners(options.nbListeners);
+		if (settings) this.settingsToListen(settings, context);
+	}
+	/**
+	* 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, context) {
+		for (const i of Object.keys(localSettings)) {
+			const res = regListenOn.exec(i);
+			if (!res) continue;
+			if (context) {
+				this.listen(context, res[0], localSettings[i]);
+				continue;
+			}
+			this.on(res[0], localSettings[i]);
+		}
+	}
+	/**
+	* 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, eventName, listener) {
+		if (typeof listener === "function") this.addListener(eventName, listener.bind(context));
+		return (...args) => this.emit(eventName, ...args);
+	}
+	/** Alias `emit` — émission synchrone (API EventEmitter standard). */
+	fire(eventName, ...args) {
+		return super.emit(eventName, ...args);
+	}
+	/**
+	* É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.
+	*/
+	async emitAsync(eventName, ...args) {
+		if (this.listenerCount(eventName) === 0) return false;
+		const handlers = this.rawListeners(eventName);
+		const result = [];
+		for (const handler of handlers) {
+			const r = Reflect.apply(handler, this, args);
+			result.push(r != null && typeof r.then === "function" ? await r : r);
+		}
+		return result;
+	}
+	/** Alias `emitAsync`. */
+	async fireAsync(eventName, ...args) {
+		return this.emitAsync(eventName, ...args);
+	}
+	/**
+	* 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}).
+	*/
+	async emitAsyncGuarded(eventName, options = {}, ...args) {
+		const results = [];
+		const errors = [];
+		if (this.listenerCount(eventName) === 0) return {
+			results,
+			errors,
+			stopped: false
+		};
+		const handlers = this.rawListeners(eventName);
+		const timeoutOption = options.timeoutMs ?? 0;
+		const perListener = typeof timeoutOption === "function";
+		const warnMs = options.warnMs ?? 0;
+		const measure = warnMs > 0;
+		for (let index = 0; index < handlers.length; index += 1) {
+			const handler = handlers[index];
+			const timeoutMs = perListener ? timeoutOption(handler, index) : timeoutOption;
+			const startedAt = measure ? Date.now() : 0;
+			let timedOut = false;
+			try {
+				const call = Promise.resolve(Reflect.apply(handler, this, args));
+				let value;
+				if (timeoutMs > 0) {
+					call.catch(() => {});
+					let timer;
+					try {
+						value = await Promise.race([call, new Promise((_, reject) => {
+							timer = setTimeout(() => {
+								timedOut = true;
+								reject(timeoutSentinel);
+							}, timeoutMs);
+							timer.unref?.();
+						})]);
+					} finally {
+						if (timer) clearTimeout(timer);
+					}
+				} else value = await call;
+				results.push(value);
+				if (measure && options.onListenerSlow) {
+					const durationMs = Date.now() - startedAt;
+					if (durationMs >= warnMs) options.onListenerSlow({
+						index,
+						listener: handler,
+						timedOut: false,
+						durationMs
+					});
+				}
+			} catch (caught) {
+				const durationMs = measure ? Date.now() - startedAt : 0;
+				const error = timedOut ? /* @__PURE__ */ new Error(`listener timeout après ${timeoutMs}ms`) : caught;
+				errors.push({
+					index,
+					error,
+					timedOut
+				});
+				if (options.onListenerError?.(error, {
+					index,
+					listener: handler,
+					timedOut,
+					durationMs
+				}) === true) return {
+					results,
+					errors,
+					stopped: true
+				};
+			}
+		}
+		return {
+			results,
+			errors,
+			stopped: false
+		};
+	}
+};
+//#endregion
+export { Event as default };

package/dist/node/FileClass.js

@@ -0,0 +1,308 @@
+import { extend } from "./Tools.js";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import mime from "mime-types";
+import fsp from "node:fs/promises";
+//#region src/FileClass.ts
+const checkPath = function(myPath) {
+	if (!myPath) throw new Error(`Bad path`);
+	if (path.isAbsolute(myPath)) return myPath;
+	return path.resolve(process.cwd(), myPath);
+};
+const regHidden = /^\./;
+const defaultWriteOption = {
+	flags: "w",
+	defaultEncoding: "utf8"
+};
+const defaultEncoding = {
+	encoding: "utf8",
+	flag: "r"
+};
+/**
+* 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()`.
+*/
+var FileClass = class FileClass {
+	stats;
+	type;
+	path;
+	parse;
+	name;
+	shortName;
+	ext;
+	mimeType = false;
+	encoding = "UTF-8";
+	extention = false;
+	dirName;
+	match = 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, options) {
+		if (!Path) throw new Error(`error fileClass Path : ${Path}`);
+		this.path = checkPath(Path);
+		if (!options?.defer) {
+			const stats = fs.lstatSync(this.path);
+			const resolved = stats.isSymbolicLink() ? this.path : fs.realpathSync.native(this.path);
+			this.hydrate(stats, resolved);
+		}
+	}
+	/**
+	* 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 async from(Path) {
+		const file = new FileClass(Path, { defer: true });
+		await file.stat();
+		return file;
+	}
+	/**
+	* 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`).
+	*/
+	async stat() {
+		const p = checkPath(this.path);
+		const stats = await fsp.lstat(p);
+		const resolved = stats.isSymbolicLink() ? p : await fsp.realpath(p);
+		this.hydrate(stats, resolved);
+		return 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.
+	*/
+	hydrate(stats, resolvedPath) {
+		this.stats = stats;
+		this.type = this.checkType();
+		this.path = resolvedPath;
+		this.parse = path.parse(this.path);
+		this.name = this.parse.name + this.parse.ext;
+		this.ext = this.parse.ext;
+		this.shortName = this.parse.name;
+		if (this.type === "File") {
+			this.mimeType = this.getMimeType(this.name);
+			this.encoding = "UTF-8";
+			this.extention = this.getExtension(this.mimeType);
+		}
+		this.dirName = this.parse.dir;
+	}
+	/**
+	* @returns le path absolu (utile pour les concat string).
+	*/
+	toString() {
+		return JSON.stringify(this.toJson(), null, "\n");
+	}
+	/**
+	* Sérialise les métadonnées du fichier en objet plain (compatible JSON.stringify).
+	*
+	* @returns objet contenant path, name, ext, stats, mime, etc.
+	*/
+	toJson() {
+		const obj = {
+			path: this.path,
+			name: this.name,
+			ext: this.ext,
+			shortName: this.shortName,
+			type: this.type,
+			stats: this.stats,
+			dirName: this.dirName,
+			parse: this.parse
+		};
+		if (this.type === "File") {
+			obj.encoding = this.encoding;
+			obj.mimeType = this.mimeType;
+			obj.extention = this.extention;
+		}
+		return obj;
+	}
+	/**
+	* Détermine le type — `"File"`, `"Directory"`, `"SymbolicLink"`, etc.
+	*
+	* @returns nom du type ou `undefined` si stats indéterminé.
+	*/
+	checkType() {
+		if (this.stats.isDirectory()) return "Directory";
+		if (this.stats.isFile()) return "File";
+		if (this.stats.isBlockDevice()) return "BlockDevice";
+		if (this.stats.isCharacterDevice()) return "CharacterDevice";
+		if (this.stats.isSymbolicLink()) return "symbolicLink";
+		if (this.stats.isFIFO()) return "Fifo";
+		if (this.stats.isSocket()) return "Socket";
+	}
+	/**
+	* 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 = "md5", hasOption) {
+		return crypto.createHash(type, hasOption).update(this.content()).digest("hex");
+	}
+	getMimeType(name) {
+		return mime.lookup(name || this.name);
+	}
+	getExtension(mimeType) {
+		if (mimeType) return mime.extension(mimeType);
+		return mime.extension(this.mimeType);
+	}
+	/**
+	* 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, options = {}) {
+		return fs.realpathSync.native(Path, options);
+	}
+	matchName(ele) {
+		if (ele instanceof RegExp) {
+			this.match = ele.exec(this.name);
+			return this.match;
+		}
+		return ele === this.name;
+	}
+	matchType(type) {
+		return type === this.type;
+	}
+	/** @returns `true` si le path pointe vers un fichier régulier. */
+	isFile() {
+		return this.type === "File";
+	}
+	/** @returns `true` si le path pointe vers un dossier. */
+	isDirectory() {
+		return this.type === "Directory";
+	}
+	/** @returns `true` si le path est un lien symbolique. */
+	isSymbolicLink() {
+		return this.type === "symbolicLink";
+	}
+	dirname() {
+		return path.dirname(this.path);
+	}
+	/** @returns `true` si le nom commence par `.` (fichier caché Unix). */
+	isHidden() {
+		return regHidden.test(this.name);
+	}
+	content(encoding) {
+		const encode = extend({}, defaultEncoding, { encoding });
+		return fs.readFileSync(this.path, encode);
+	}
+	/**
+	* 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) {
+		const encode = extend({}, defaultEncoding, { encoding });
+		if (this.type === "symbolicLink") {
+			const linked = fs.readlinkSync(this.path, encode);
+			return fs.readFileSync(linked, encode);
+		}
+		return fs.readFileSync(this.path, encode);
+	}
+	async readAsync(encoding) {
+		if (this.type === "symbolicLink") {
+			const linked = await fsp.readlink(this.path);
+			return fsp.readFile(linked, encoding);
+		}
+		return fsp.readFile(this.path, encoding);
+	}
+	readByLine(callback, encoding) {
+		const res = this.content(encoding);
+		let nb = 0;
+		res.toString().split("\n").forEach((line) => {
+			callback(line, ++nb);
+		});
+		return res;
+	}
+	/**
+	* É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, options) {
+		fs.writeFileSync(this.path, data, extend({}, defaultWriteOption, options));
+	}
+	/**
+	* Déplace/renomme le fichier (synchronous).
+	*
+	* @param target - chemin de destination.
+	* @returns nouvelle instance FileClass pointant vers `target`.
+	*/
+	move(target) {
+		fs.renameSync(this.path, target);
+		return new FileClass(target);
+	}
+	/**
+	* 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`.
+	*/
+	async moveAsync(target) {
+		await fsp.rename(this.path, target);
+		return FileClass.from(target);
+	}
+	/** Supprime le fichier du filesystem (synchronous, irréversible). */
+	unlink() {
+		fs.unlinkSync(this.path);
+	}
+	/** Supprime le fichier du filesystem en **async** (`fsp.unlink`). */
+	async unlinkAsync() {
+		await fsp.unlink(this.path);
+	}
+};
+//#endregion
+export { FileClass as default };

package/dist/node/Nodefony.js

@@ -0,0 +1,78 @@
+import { version } from "./package.js";
+import { randomUUID, randomUUIDv7 } from "node:crypto";
+//#region src/Nodefony.ts
+/**
+* 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 `?.`.
+*/
+var Nodefony = class Nodefony {
+	/** Version du package `nodefony` (lue depuis `package.json` au build). */
+	static version = version;
+	static #kernel = null;
+	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() {
+		return Nodefony.#kernel;
+	}
+	/**
+	* 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) {
+		Nodefony.#kernel = k;
+	}
+	/**
+	* 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() {
+		return randomUUID();
+	}
+	/**
+	* 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() {
+		return randomUUIDv7();
+	}
+};
+//#endregion
+export { Nodefony };