nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/config/reservedEnv.js

@@ -0,0 +1,118 @@
+//#region src/config/reservedEnv.ts
+/**
+* Le catalogue des variables réservées, indexé par nom.
+*
+* Ajouter une entrée ici est OBLIGATOIRE dès qu'un code du framework écrit une
+* `NF_*` dans l'environnement d'un process : sans elle, la variable ressort en
+* « inconnue » chez tout utilisateur qui lance la commande au mauvais moment.
+*/
+const RESERVED_ENV = Object.freeze({
+	NF_CLI_DELEGATED: {
+		name: "NF_CLI_DELEGATED",
+		role: "posée par le lanceur du CLI quand il passe la main au `nodefony` du projet (garde anti-boucle)"
+	},
+	NF_CLI_DEBUG: {
+		name: "NF_CLI_DEBUG",
+		role: "trace la décision du lanceur du CLI sur la sortie d'erreur"
+	},
+	NF_MODE_START: {
+		name: "NF_MODE_START",
+		role: "posée par la commande de démarrage — le mode par lequel l'application a été lancée"
+	},
+	NF_CLUSTER: {
+		name: "NF_CLUSTER",
+		role: "posée par le maître de grappe dans chaque worker"
+	},
+	NF_MCP_TOKEN: {
+		name: "NF_MCP_TOKEN",
+		role: "jeton d'accès au serveur MCP de l'application, lu par le client de l'agent (`nodefony ai:mcp --auth`)"
+	},
+	NF_ENV: {
+		name: "NF_ENV",
+		role: "environnement de déploiement quand il diffère du mode runtime (`APP_ENV` gagne)"
+	},
+	NF_START: {
+		name: "NF_START",
+		role: "point d'entrée que le Kernel démarre, quand il ne doit pas être celui du projet"
+	},
+	NF_WORKERS: {
+		name: "NF_WORKERS",
+		role: "nombre de workers de la grappe (`nodefony cluster -w N`, en variable)"
+	},
+	NF_CLUSTER_PROBE: {
+		name: "NF_CLUSTER_PROBE",
+		role: "coupe la sonde du maître de grappe quand elle vaut `0`"
+	},
+	NF_POD_NAME: {
+		name: "NF_POD_NAME",
+		role: "nom du pod, dont se dérive l'identité d'origine du backplane temps réel"
+	},
+	NF_INSTANCE_ID: {
+		name: "NF_INSTANCE_ID",
+		role: "identifiant d'instance rendu par le plan d'administration (défaut : le pid)"
+	},
+	NF_DEV_CHILD: {
+		name: "NF_DEV_CHILD",
+		role: "posée par le superviseur de développement dans l'application qu'il relance"
+	},
+	NF_DEV_PORTS: {
+		name: "NF_DEV_PORTS",
+		role: "ports que le superviseur de développement doit libérer, imposés par l'opérateur"
+	},
+	NF_BOOT_TIMEOUT_MS: {
+		name: "NF_BOOT_TIMEOUT_MS",
+		role: "délai au-delà duquel un démarrage est déclaré perdu"
+	},
+	NF_BOOT_WARN_MS: {
+		name: "NF_BOOT_WARN_MS",
+		role: "délai au-delà duquel un démarrage lent est signalé"
+	},
+	NF_KERNEL_TRACE_FILE: {
+		name: "NF_KERNEL_TRACE_FILE",
+		role: "fichier où le Kernel écrit sa trace de démarrage (diagnostic)"
+	},
+	NF_NO_TTY: {
+		name: "NF_NO_TTY",
+		role: "force le rendu non interactif, quel que soit le terminal"
+	},
+	NF_PERF_PROBE: {
+		name: "NF_PERF_PROBE",
+		role: "arme la sonde de performance du pipeline HTTP"
+	},
+	NF_ORM_FLOW: {
+		name: "NF_ORM_FLOW",
+		role: "arme la sonde de flux de l'ORM"
+	},
+	NF_ORM_HEARTBEAT_MS: {
+		name: "NF_ORM_HEARTBEAT_MS",
+		role: "période du battement de cœur qui surveille les connecteurs de l'ORM"
+	},
+	NF_REALTIME_DRIVER: {
+		name: "NF_REALTIME_DRIVER",
+		role: "pilote du backplane temps réel (mémoire, Redis…)"
+	},
+	NF_REALTIME_BACKPLANE_SECRET: {
+		name: "NF_REALTIME_BACKPLANE_SECRET",
+		role: "secret qui scelle les enveloppes du backplane temps réel"
+	},
+	NF_REALTIME_BACKPLANE_NAMESPACE: {
+		name: "NF_REALTIME_BACKPLANE_NAMESPACE",
+		role: "espace de noms du backplane — ce qui cloisonne deux applications sur un même bus"
+	}
+});
+/** Cette variable est-elle posée par le framework lui-même ? */
+function isReservedEnv(name) {
+	return Object.hasOwn(RESERVED_ENV, name);
+}
+/**
+* Le rôle d'une variable réservée, ou `null` si elle ne l'est pas.
+*
+* @param name - le nom lu dans l'environnement.
+* @returns la phrase à rendre à l'utilisateur, ou `null`.
+*/
+function reservedEnvRole(name) {
+	const entry = RESERVED_ENV[name];
+	return entry ? entry.role : null;
+}
+//#endregion
+export { RESERVED_ENV, isReservedEnv, reservedEnvRole };

package/dist/node/config/schema.js

@@ -0,0 +1,134 @@
+import { z } from "zod";
+//#region src/config/schema.ts
+/**
+* Schéma Zod de la config d'application — validé au resolve de `defineConfig` (D1).
+*
+* Vit dans le CORE (zod = peerDep core, back-only) : `import { defineConfig } from
+* "nodefony"` valide tout seul, sans que chaque app porte son propre schéma. But :
+* planter PROPREMENT au boot (message clair) sur une config malformée, plutôt qu'un
+* `Cannot read properties of undefined` plus tard en runtime.
+*
+* Le schéma DÉCRIT (il ne dérive pas les défauts — ceux-ci sont dans `./defaults`).
+* Tous les champs sont `.optional()` : il rejette les TYPES/valeurs invalides, pas
+* l'absence (le merge a déjà rempli les défauts ; le Kernel a des fallbacks
+* résiduels). Les clés inconnues — `module-<x>` (overrides validés par chaque
+* module), `App`, `cluster`… — sont ignorées (objet zod non-strict).
+*/
+const serverSchema = z.object({ port: z.number().int().positive().optional().describe("Port d'écoute du serveur HTTP en clair. Défaut : 5151.") });
+const logSchema = z.object({
+	active: z.boolean().optional().describe("Active le logger Syslog. Défaut : true."),
+	debug: z.union([z.string(), z.array(z.string())]).optional().describe("Filtre de debug : `\"*\"` (tout), une liste de modules/scopes, ou `[]` (rien). Défaut prod : `[]` ; dev : `\"*\"`."),
+	requestFormat: z.enum([
+		"auto",
+		"default",
+		"pretty",
+		"json"
+	]).optional().describe("Format de log des requêtes HTTP. `auto` = pretty en dev / json en prod. Défaut : `auto`."),
+	buffered: z.union([z.boolean(), z.literal("auto")]).optional().describe("Bufferise les écritures de log (perf). `auto` décide selon l'env. Défaut : `auto`."),
+	driver: z.enum([
+		"stdout",
+		"file",
+		"null"
+	]).optional().describe("Transport de log principal. `stdout` (cloud-native, collecteur externe), `file`, ou `null` (jeté). Override env : `NF_LOG_DRIVER`. Défaut : `stdout`."),
+	dir: z.string().optional().describe("Répertoire des logs (`.log` + JSONL queryable + viewer Studio), sous cwd. Défaut : `logs`."),
+	file: z.object({
+		path: z.string().optional().describe("Chemin explicite du fichier de log. Défaut : `<dir>/nodefony-<pid>.log`."),
+		sync: z.boolean().optional().describe("Écriture fichier synchrone (sûre mais lente). Défaut : false.")
+	}).optional().describe("Options du driver `file`."),
+	maxStack: z.number().int().positive().optional().describe("Profondeur du ring de relecture du backplane (driver `memory`). Non défini : 2000 en dev, repli prod-safe sinon."),
+	queryFile: z.object({
+		path: z.string().optional().describe("Chemin du JSONL relu par le driver de query `file`."),
+		maxScanBytes: z.number().int().positive().optional().describe("Plafond d'octets scannés en fin de fichier par query.")
+	}).optional().describe("Options du driver de relecture `file` (query plane JSONL)."),
+	queryDriver: z.string().optional().describe("Driver de relecture du backplane de log (query plane). Défaut `auto` : s'adapte au mode de lancement (mono → `memory`, worker de cluster → `cluster-file`, vue unifiée). Valeur explicite (memory/file/loki/…) = surcharge."),
+	loki: z.object({ url: z.string().describe("URL d'ingestion Grafana Loki.") }).optional().describe("Cible Grafana Loki (si driver/superposition Loki actif)."),
+	opensearch: z.object({ url: z.string().describe("URL du cluster OpenSearch.") }).optional().describe("Cible OpenSearch (si superposition active).")
+}).describe("Observabilité : logger Syslog et ses transports.");
+const serversSchema = z.object({
+	statics: z.boolean().optional().describe("Monte le service de fichiers statiques. Défaut : true."),
+	http: z.union([serverSchema, z.literal(false)]).optional().describe("Serveur HTTP/1.1 en clair (port 5151 par défaut). `false` = désactivé (déploiement TLS-only) — le WS en clair tombe avec."),
+	https: z.union([z.object({
+		port: z.number().int().positive().optional().describe("Port d'écoute HTTPS. Défaut : 5152."),
+		protocol: z.enum(["1.1", "2.0"]).optional().describe("Version HTTP servie sur le port TLS. `2.0` = HTTP/2 (h2). Défaut : `2.0`.")
+	}), z.literal(false)]).optional().describe("Serveur HTTPS (TLS), HTTP/2 par défaut (port 5152). `false` = désactivé — cas NOMINAL cloud-native (TLS terminé à l'ingress/LB, le pod sert en clair) ; le WSS tombe avec."),
+	ws: z.object({}).optional().describe("Serveur WebSocket en clair (adossé au serveur HTTP)."),
+	wss: z.object({}).optional().describe("Serveur WebSocket sécurisé (adossé au serveur HTTPS)."),
+	portPolicy: z.enum(["auto", "strict"]).optional().describe("Que faire si le port désiré est DÉJÀ OCCUPÉ. `auto` = prendre le prochain port libre (l'app boote quand même, le décalage est ANNONCÉ) — confort de dev : plusieurs apps côte à côte. `strict` = échec fatal (EADDRINUSE). Défaut : `auto` en développement, `strict` en production ET en test. En production le port est un CONTRAT (service k8s, ingress, sonde de santé) : écouter ailleurs en silence donnerait un pod « sain » que personne n'atteint. En test, un port occupé signale un serveur resté debout — le banc doit s'arrêter, pas viser un autre port."),
+	portRetryAttempts: z.number().int().min(0).optional().describe("En `portPolicy: auto`, nombre de ports essayés APRÈS le port désiré avant d'abandonner. Défaut : 20.")
+}).describe("Serveurs réseau activés au boot (HTTP/HTTPS/WS/WSS + statics).");
+/**
+* Schéma de la config app résolue. Exposé pour l'introspection (Studio :
+* `z.toJSONSchema(appConfigSchema)` → panneau de config + formulaire éditable).
+*
+* Chaque champ porte un `.describe()` FR (rôle + défaut) → consommé par le
+* panneau de config Studio (`/nodefony/config`, carte de l'app).
+*/
+const appConfigSchema = z.object({
+	modules: z.array(z.unknown()).optional().describe("Manifeste ORDONNÉ des modules chargés (`use(name, config, opts)` ou nom). L'ordre = ordre de boot (dépendances inter-modules). Défaut : `[]` (l'app déclare)."),
+	locale: z.string().optional().describe("Locale par défaut de l'application (i18n). Défaut : `en_en`."),
+	templating: z.string().optional().describe("Moteur de templates par défaut. Défaut : `eta`."),
+	orm: z.string().optional().describe("ORM par défaut (clé du driver multi-ORM). Sans défaut framework — piloté par l'app / le chantier ORM."),
+	packageManager: z.enum([
+		"npm",
+		"yarn",
+		"pnpm",
+		"bun"
+	]).optional().describe("Gestionnaire de paquets utilisé par les commandes (install/outdated). Défaut : `npm`."),
+	domain: z.string().optional().describe("Adresse d'écoute du serveur (`Kernel.setDomain`). Dev : `127.0.0.1` ; prod : `0.0.0.0`. Défaut : `localhost`."),
+	domainAlias: z.array(z.string()).optional().describe("Hôtes alternatifs acceptés par la validation Host (opt-in, croise `http.trustedHosts`). Défaut : aucun."),
+	domainCheck: z.boolean().optional().describe("Active la validation de l'en-tête Host (anti rebinding/spoofing). Opt-in app/sécu. Défaut : false."),
+	servers: serversSchema.optional(),
+	cluster: z.unknown().optional().describe("Topologie cluster (workers, backplane). Forme détaillée résolue par `resolveTopology` ; lue standalone par le master AVANT le boot."),
+	timing: z.object({
+		enabled: z.boolean().nullable().optional().describe("Sonde de phases du pipeline (parse/resolve/firewall/initialize/action/render/send) : la matière du waterfall (Studio, debug bar, profiler). `null` (défaut) = PAS D'AVIS → active hors production, éteinte en production. Un booléen EXPLICITE gagne : `true` allume la sonde en production (diagnostic à chaud — coût mesuré, cf docs) ; `false` l'éteint partout. Surchargeable sans redéployer : `NF__APP__TIMING__ENABLED=true`."),
+		verbose: z.boolean().optional().describe("Trace DEBUG détaillant chaque phase au teardown (1 log par requête). Implique `enabled`. Défaut : false — à n'allumer que le temps d'un diagnostic (le volume nominal n'est pas un signal).")
+	}).optional().describe("Instrumentation du pipeline (timing des phases). Éteinte en production par défaut : allumée, elle alloue le tableau des phases + une Map par requête et appelle `performance.now()` à chaque borne."),
+	shutdownDeadline: z.number().int().nonnegative().optional().describe("Deadline GLOBALE du shutdown (ms) : au-delà, sortie forcée code 1 même si un listener onTerminate pend. Filet cloud-native — garder < grace period de l'orchestrateur (30 s k8s, 10 s Docker). 0 = désactivé. Défaut : 15000."),
+	log: logSchema.optional()
+});
+/**
+* JSON Schema introspectable de la config d'application — destiné au panneau de
+* config Studio (`/nodefony/config`, carte de l'app). Documenté via les
+* `.describe()` du schéma (rôle + défaut de chaque champ).
+*/
+function appConfigJsonSchema() {
+	return z.toJSONSchema(appConfigSchema);
+}
+/**
+* Aplati les issues Zod en libellés `chemin.complet: message`, en DESCENDANT
+* dans les unions : une `invalid_union` (ex. `servers.https` = objet | `false`)
+* masquerait le champ fautif (`servers.http: Invalid input`) — on reprend les
+* issues de la branche la plus informative (celle qui pointe un champ interne)
+* pour garder le diagnostic précis (`servers.http.port: …`).
+*/
+function flattenZodIssues(issues, base = []) {
+	const out = [];
+	for (const issue of issues) {
+		const path = [...base, ...issue.path];
+		const branches = issue.errors;
+		if (issue.code === "invalid_union" && branches?.length) {
+			const best = branches.find((b) => b.some((i) => i.path.length > 0)) ?? branches[0];
+			out.push(...flattenZodIssues(best, path));
+			continue;
+		}
+		out.push(`${path.join(".") || "(root)"}: ${issue.message}`);
+	}
+	return out;
+}
+/**
+* Valide la config app résolue ; lève une erreur au message agrégé si invalide.
+*
+* Appelée par `defineConfig().resolve()` après le deep-merge avec les défauts.
+*
+* @param options - config app résolue à valider.
+* @throws Error si la config ne respecte pas {@link appConfigSchema}.
+*/
+function validateAppConfig(options) {
+	const result = appConfigSchema.safeParse(options);
+	if (!result.success) {
+		const issues = flattenZodIssues(result.error.issues).join(" · ");
+		throw new Error(`[nodefony] Configuration d'application invalide : ${issues}`);
+	}
+}
+//#endregion
+export { appConfigJsonSchema, appConfigSchema, validateAppConfig };

package/dist/node/config/use.js

@@ -0,0 +1,24 @@
+//#region src/config/use.ts
+/**
+* Construit une entrée de manifeste `modules` avec config colocalisée + typée.
+*
+* Le générique `N` capture le nom du module au call-site → `config` est
+* contraint à {@link ConfigOf}<N> (autocomplétion des clés du module ciblé).
+* Le type de RETOUR est volontairement élargi à {@link ModuleEntryInput} (la
+* config stockée dans le tableau est hétérogène) : le typage fort vit à l'appel,
+* pas dans le conteneur — exactement le pattern `defineNuxtConfig`/`app.use`.
+*
+* @param name - nom du module à charger (`KnownModule` autocomplété, string tierce acceptée).
+* @param config - config du module, typée selon le registre (optionnelle).
+* @param opts - politique + garde de chargement (`policy`/`when`).
+* @returns une entrée `{ name, config?, policy?, when? }` pour l'array `modules`.
+*/
+function use(name, config, opts) {
+	const entry = { name };
+	if (config !== void 0) entry.config = config;
+	if (opts?.policy !== void 0) entry.policy = opts.policy;
+	if (opts?.when !== void 0) entry.when = opts.when;
+	return entry;
+}
+//#endregion
+export { use };

package/dist/node/finder/File.js

@@ -0,0 +1,49 @@
+import FileClass from "../FileClass.js";
+import FileResult from "./FileResult.js";
+//#region src/finder/File.ts
+var File = class File extends FileClass {
+	parent = null;
+	childrens = new FileResult();
+	constructor(path, parent = null, options) {
+		super(path, options);
+		this.parent = parent;
+	}
+	/**
+	* Construit un `File` SANS `lstatSync` bloquant — stat résolu en async.
+	* À utiliser dans le Finder pour ne pas bloquer l'event-loop par entrée.
+	*
+	* @param path - chemin du fichier/dossier.
+	* @param parent - `File` parent (arborescence Finder), `null` à la racine.
+	* @returns instance `File` hydratée (stats async).
+	*/
+	static async from(path, parent = null) {
+		const file = new File(path, parent, { defer: true });
+		await file.stat();
+		return file;
+	}
+	get length() {
+		return this.childrens.length;
+	}
+	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;
+		}
+		obj.childrens = this.childrens.toJson();
+		obj.parent = this.parent?.toJson();
+		return obj;
+	}
+};
+//#endregion
+export { File as default };

package/dist/node/finder/FileResult.js

@@ -0,0 +1,86 @@
+import Result from "./Result.js";
+//#region src/finder/FileResult.ts
+var FileResult = class FileResult extends Result {
+	constructor(res) {
+		super(res);
+	}
+	toString() {
+		let txt = "";
+		for (const info of this) txt += `${info.name}\n`;
+		return txt;
+	}
+	toJson(json = []) {
+		for (const info of this) switch (info.type) {
+			case "File":
+				json.push(info.toJson());
+				break;
+			case "symbolicLink":
+			case "Directory": {
+				const dir = info.toJson();
+				if (info.childrens) dir.childrens = info.childrens.toJson();
+				json.push(dir);
+				break;
+			}
+		}
+		return JSON.stringify(json);
+	}
+	uniq() {
+		const seen = /* @__PURE__ */ new Set();
+		const result = new FileResult();
+		for (const info of this) {
+			const key = info.path;
+			if (!seen.has(key)) {
+				seen.add(key);
+				result.push(info);
+			}
+		}
+		return result;
+	}
+	findByName(name, result = new FileResult()) {
+		for (const info of this) {
+			if (info.matchName(name)) result.push(info);
+			info.childrens.findByName(name, result);
+		}
+		return result.uniq();
+	}
+	getDirectories(result = new FileResult()) {
+		for (const info of this) switch (info.type) {
+			case "Directory":
+				result.push(info);
+				info.childrens.getDirectories(result);
+				break;
+			case "symbolicLink": info.childrens.getDirectories(result);
+		}
+		return result;
+	}
+	getFiles(result = new FileResult()) {
+		for (const info of this) switch (info.type) {
+			case "File":
+				result.push(info);
+				break;
+			case "symbolicLink":
+			case "Directory": info.childrens.getFiles(result);
+		}
+		return result;
+	}
+	sortByName(result = new FileResult()) {
+		const res = this.sort((a, b) => {
+			if (a.name.toString() > b.name.toString()) return 1;
+			if (a.name.toString() < b.name.toString()) return -1;
+			return 0;
+		});
+		if (res) return result.concat(res);
+		return this;
+	}
+	sortByType(result = new FileResult()) {
+		const res = this.sort((a, b) => {
+			if (a.type.toString() > b.type.toString()) return 1;
+			if (a.type.toString() < b.type.toString()) return -1;
+			return 0;
+		});
+		if (res) return result.concat(res);
+		return this;
+	}
+};
+//#endregion
+export { FileResult as default };

package/dist/node/finder/Finder.js

@@ -0,0 +1,201 @@
+import { extend, typeOf } from "../Tools.js";
+import FileClass from "../FileClass.js";
+import Event from "../Event.js";
+import FileResult from "./FileResult.js";
+import File from "./File.js";
+import path from "node:path";
+import fsp from "node:fs/promises";
+//#region src/finder/Finder.ts
+const defaultSettings = {
+	recurse: false,
+	depth: 10,
+	seeHidden: false,
+	match: null,
+	exclude: null,
+	excludeFile: null,
+	excludeDir: null,
+	followSymLink: false
+};
+const checkExclude = function(info, options) {
+	if (!(options.exclude || options.excludeDir || options.excludeFile)) return false;
+	if (options.exclude && info.matchName(options.exclude)) return true;
+	if (options.excludeDir && info.isDirectory() && info.matchName(options.excludeDir)) return true;
+	if (options.excludeFile && info.isFile() && info.matchName(options.excludeFile)) return true;
+	return false;
+};
+const checkMatch = function(info, options = {}, result) {
+	let match = false;
+	let rec = void 0;
+	if (!(options.matchFile || options.matchDir || options.match)) {
+		result.push(info);
+		if (info.type) {
+			this.totals[info.type]++;
+			this.fire(`on${info.type}`, info, this);
+		}
+		return true;
+	}
+	if (options.matchDir) {
+		if (info.isDirectory()) {
+			if (info.matchName(options.matchDir)) match = true;
+			else return false;
+		}
+	}
+	if (options.matchFile) {
+		if (info.isFile()) match = Boolean(info.matchName(options.matchFile));
+	}
+	if (options.match) {
+		if (info.matchName(options.match)) match = true;
+		else {
+			match = false;
+			rec = info.type;
+		}
+	}
+	if (match) {
+		result.push(info);
+		this.totals[info.type]++;
+		this.fire(`on${info.type}`, info, this);
+		return true;
+	}
+	switch (rec) {
+		case "Directory":
+		case "symbolicLink":
+			result.push(info);
+			this.totals[info.type]++;
+			this.fire(`on${info.type}`, info, this);
+			return true;
+		default: return false;
+	}
+};
+async function parser(file, result = new FileResult(), options, depth = null, parent = null) {
+	if (depth === 0) return result;
+	if (parent) parent.childrens = result;
+	try {
+		let res = null;
+		if (file.type !== "symbolicLink") res = await fsp.readdir(file.path, {
+			encoding: "utf8",
+			withFileTypes: false
+		});
+		else if (options.followSymLink) res = await fsp.readlink(file.path);
+		if (res && res.length) {
+			const paths = [];
+			for (let i = 0; i < res.length; i++) paths.push(path.resolve(file.path, res[i]));
+			const infos = await Promise.all(paths.map((p) => File.from(p, parent)));
+			for (const info of infos) {
+				const hidden = info.isHidden();
+				if (hidden && !options.seeHidden) continue;
+				if (checkExclude(info, options)) continue;
+				let symLink = null;
+				if (info.type === "symbolicLink" && options.followSymLink) try {
+					const read = path.resolve(info.dirName, await fsp.readlink(info.path));
+					symLink = await File.from(read, info);
+				} catch (e) {
+					this.fire("onError", e, this);
+					continue;
+				}
+				if (!checkMatch.call(this, info, options, result)) continue;
+				if (hidden) {
+					this.totals.hidden++;
+					this.fire("onHidden", info, this);
+				}
+				if (info.type === "File") continue;
+				if (!options.recurse) continue;
+				switch (info.type) {
+					case "Directory": {
+						const myDepth = depth === null ? null : depth - 1;
+						await parser.call(this, info, void 0, options, myDepth, info);
+						break;
+					}
+					case "symbolicLink": if (symLink?.isDirectory()) {
+						const myDepth = depth === null ? null : depth - 1;
+						await parser.call(this, symLink, void 0, options, myDepth, info);
+					}
+				}
+			}
+		}
+		return result;
+	} catch (e) {
+		this.fire("onError", e);
+		throw e;
+	}
+}
+var Finder = class extends Event {
+	settings;
+	totals;
+	constructor(settings = {}) {
+		super(settings);
+		this.settings = extend({}, defaultSettings, settings);
+		this.totals = {
+			Directory: 0,
+			File: 0,
+			BlockDevice: 0,
+			CharacterDevice: 0,
+			symbolicLink: 0,
+			Fifo: 0,
+			Socket: 0,
+			hidden: 0
+		};
+	}
+	clean() {
+		this.removeAllListeners();
+		for (const total of Object.keys(this.totals)) this.totals[total] = 0;
+	}
+	checkPath(Path) {
+		const type = typeOf(Path);
+		const result = new FileResult();
+		switch (true) {
+			case type === "string":
+				result.push(new File(Path));
+				return result;
+			case type === "array":
+				for (const p of Path) result.push(new File(p));
+				return result;
+			case Path instanceof FileClass:
+				result.push(new File(Path.path));
+				return result;
+			default: throw new Error(`Bad Path type: ${type} Accept only String, Array or fileClass`);
+		}
+	}
+	/**
+	* Variante **async** de {@link checkPath} — résout la (les) racine(s) via
+	* `File.from()` (pas de `lstatSync`). Utilisée par `in()` pour ne pas bloquer
+	* l'event-loop dès la résolution du point d'entrée.
+	*
+	* @param Path - string, array de strings, ou FileClass.
+	* @returns `Result` contenant les `File` racines hydratés.
+	*/
+	async checkPathAsync(Path) {
+		const type = typeOf(Path);
+		const result = new FileResult();
+		switch (true) {
+			case type === "string":
+				result.push(await File.from(Path));
+				return result;
+			case type === "array": {
+				const files = await Promise.all(Path.map((p) => File.from(p)));
+				for (const f of files) result.push(f);
+				return result;
+			}
+			case Path instanceof FileClass:
+				result.push(await File.from(Path.path));
+				return result;
+			default: throw new Error(`Bad Path type: ${type} Accept only String, Array or fileClass`);
+		}
+	}
+	async in(Path, settings = {}) {
+		let result = null;
+		try {
+			result = await this.checkPathAsync(Path);
+			this.settingsToListen(settings);
+			const options = extend({}, this.settings, settings);
+			for await (const res of result) await parser.call(this, res, void 0, options, options.depth, res);
+		} catch (e) {
+			this.fire("onError", e);
+			throw e;
+		}
+		this.fire("onFinish", result, this.totals, this);
+		this.clean();
+		return result;
+	}
+};
+//#endregion
+export { Finder as default };

package/dist/node/finder/Result.js

@@ -0,0 +1,45 @@
+//#region src/finder/Result.ts
+var Result = class Result extends Array {
+	constructor(res) {
+		if (res) {
+			if (Array.isArray(res)) {
+				super();
+				for (const item of res) this.push(item);
+				if (res instanceof Result) res.clean();
+			} else throw new Error(`Result bad type must be an array : ${res}`);
+		} else super();
+	}
+	toJson(json = []) {
+		for (const ele of this) json.push(ele);
+		return JSON.stringify(json);
+	}
+	toString() {
+		const json = [];
+		for (const ele of this) json.push(ele);
+		return JSON.stringify(json, null, "\n");
+	}
+	clean(callback) {
+		if (callback) Array.prototype.forEach.call(this, (ele) => {
+			return callback(ele);
+		});
+		this.length = 0;
+	}
+	query(query, logger = false, options = {}, sevrity = "INFO", clean = false) {
+		const res = new Result(this.filter((data) => {
+			if (data.query(query, logger, options, sevrity)) return data;
+			return null;
+		}));
+		if (clean) this.clean();
+		return res;
+	}
+	queryGrep(query, grep, clean = false) {
+		const res = new Result(this.filter((data) => {
+			if (data.queryGrep(query, grep)) return data;
+			return null;
+		}));
+		if (clean) this.clean();
+		return res;
+	}
+};
+//#endregion
+export { Result as default };