nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/client/Service.js

@@ -0,0 +1,344 @@
+import Container from "./Container.js";
+import Event from "./Event.js";
+import Pdu from "./syslog/Pdu.js";
+import Syslog from "./syslog/Syslog.js";
+//#region src/Service.ts
+const defaultOptions = { events: { nbListeners: 20 } };
+const PERF_PROBE_SUB = typeof process !== "undefined" && process.env?.NF_PERF_PROBE === "1";
+function perfMark(field) {
+	const p = globalThis.__nfPerfProbe;
+	if (p && p.t0 !== 0n) p[field] += Number(process.hrtime.bigint() - p.t0);
+}
+const defaultSyslogSettings = {
+	moduleName: "SERVICE ",
+	defaultSeverity: "INFO"
+};
+/**
+* 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.
+*/
+var Service = class Service {
+	name;
+	options;
+	container;
+	kernel;
+	syslog;
+	#nc;
+	#trackedListeners = null;
+	#sharedNc = false;
+	get notificationsCenter() {
+		return this.#nc;
+	}
+	get nc() {
+		if (!this.#nc) throw new Error(`${this.name}: notificationsCenter not initialized`);
+		return this.#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, container, notificationsCenter, options = {}) {
+		if (PERF_PROBE_SUB) perfMark("svcStartNs");
+		this.name = name;
+		this.container = container instanceof Container ? container : new Container();
+		const { events: evOpts, ...svcOptions } = options;
+		const effectiveEvents = evOpts ?? defaultOptions.events;
+		this.options = svcOptions;
+		if (PERF_PROBE_SUB) perfMark("svcOptsNs");
+		this.kernel = this.container.get("kernel");
+		this.syslog = this.container.get("syslog");
+		if (PERF_PROBE_SUB) perfMark("svcLookupsNs");
+		if (!this.syslog) {
+			const syslogSettings = {
+				...defaultSyslogSettings,
+				moduleName: this.name,
+				...this.options.syslog
+			};
+			this.syslog = new Syslog(syslogSettings);
+			this.container.set("syslog", this.syslog);
+		}
+		if (notificationsCenter instanceof Event) {
+			this.#sharedNc = true;
+			this.#nc = notificationsCenter;
+			this.attachConfiguredListeners(options);
+			const shared = this.#nc.getMaxListeners();
+			const wanted = effectiveEvents?.nbListeners ?? 0;
+			if (wanted > shared) this.#nc.setMaxListeners(wanted);
+		} else if (notificationsCenter !== false) {
+			this.#nc = new Event(this.options, this, this.options);
+			if (effectiveEvents?.nbListeners) this.#nc.setMaxListeners(effectiveEvents.nbListeners);
+			if (!this.kernel || this.kernel.container !== this.container) this.container.set("notificationsCenter", this.#nc);
+		}
+		if (PERF_PROBE_SUB) perfMark("svcEventNs");
+	}
+	/**
+	* 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}.
+	*/
+	attachConfiguredListeners(localSettings) {
+		for (const key of Object.keys(localSettings)) {
+			if (!/^on(.+)$/.test(key)) continue;
+			const handler = localSettings[key];
+			if (typeof handler !== "function") continue;
+			this.on(key, handler.bind(this));
+		}
+	}
+	/**
+	* 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 = "production", debug = false, options) {
+		return this.syslog ? this.syslog.init(environment, debug, options) : null;
+	}
+	/** Renvoie le nom logique du service (utilisé comme `msgid` syslog par défaut). */
+	getName() {
+		return this.name;
+	}
+	/**
+	* 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 = false) {
+		if (this.#nc && this.#sharedNc && this.#trackedListeners) for (const [event, listeners] of this.#trackedListeners) for (const listener of listeners) this.#nc.removeListener(event, listener);
+		this.#trackedListeners = null;
+		this.#sharedNc = false;
+		if (this.syslog && syslog) this.syslog.reset();
+		this.syslog = null;
+		this.#nc = void 0;
+		this.container = null;
+		this.kernel = null;
+	}
+	/**
+	* É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, severity, msgid, msg) {
+		try {
+			if (!msgid) msgid = this.name;
+			if (this.syslog) return this.syslog.log(pci, severity, msgid, msg);
+			return new Pdu(pci, severity, this.name, msgid, msg);
+		} catch (e) {
+			console.log(severity, msgid, msg, " : ", pci);
+			console.warn(e);
+			return new Pdu(e, "ERROR", this.name, msgid, msg);
+		}
+	}
+	/** Raccourci debug — log severity `DEBUG` + `console.debug` formaté. */
+	logger(pci, ...args) {
+		console.debug(Syslog.wrapper(this.log(pci, "DEBUG")).text, pci, ...args);
+	}
+	/** Comme {@link logger} mais `console.trace` (avec stack trace). */
+	trace(pci, ...args) {
+		console.trace(Syslog.wrapper(this.log(pci, "DEBUG")).text, pci, ...args);
+	}
+	trackListener(eventName, listener) {
+		if (this.#trackedListeners === null) this.#trackedListeners = /* @__PURE__ */ new Map();
+		const list = this.#trackedListeners.get(eventName) ?? [];
+		list.push(listener);
+		this.#trackedListeners.set(eventName, list);
+	}
+	untrackListener(eventName, listener) {
+		const map = this.#trackedListeners;
+		if (!map) return;
+		const list = map.get(eventName);
+		if (!list) return;
+		const idx = list.indexOf(listener);
+		if (idx !== -1) list.splice(idx, 1);
+		if (list.length === 0) map.delete(eventName);
+	}
+	/** Liste les noms d'événements ayant au moins un listener. */
+	eventNames() {
+		return this.nc.eventNames();
+	}
+	/** Alias `emit` — émet l'événement de manière synchrone. */
+	fire(eventName, ...args) {
+		return this.nc.emit(eventName, ...args);
+	}
+	/** Émet l'événement et attend que tous les listeners async résolvent. */
+	fireAsync(eventName, ...args) {
+		return this.nc.emitAsync(eventName, ...args);
+	}
+	/** Émet l'événement (API EventEmitter standard). */
+	emit(eventName, ...args) {
+		return this.nc.emit(eventName, ...args);
+	}
+	/** Émet et attend les listeners async — équivalent de {@link fireAsync}. */
+	emitAsync(eventName, ...args) {
+		return this.nc.emitAsync(eventName, ...args);
+	}
+	/**
+	* 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, options, ...args) {
+		return this.nc.emitAsyncGuarded(eventName, options, ...args);
+	}
+	/** Enregistre un listener (tracké pour cleanup). Voir aussi {@link on}. */
+	addListener(eventName, listener) {
+		this.nc.addListener(eventName, listener);
+		this.trackListener(eventName, listener);
+		return 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, listener) {
+		return this.nc.listen(this, eventName, listener);
+	}
+	/** Enregistre un listener (tracké pour cleanup). Alias EventEmitter de {@link addListener}. */
+	on(eventName, listener) {
+		this.nc.on(eventName, listener);
+		this.trackListener(eventName, listener);
+		return this;
+	}
+	/** Enregistre un listener one-shot — auto-retiré après le premier `emit`. */
+	once(eventName, listener) {
+		this.nc.once(eventName, listener);
+		this.trackListener(eventName, listener);
+		return this;
+	}
+	/** Retire un listener (alias EventEmitter de {@link removeListener}). */
+	off(eventName, listener) {
+		this.nc.off(eventName, listener);
+		this.untrackListener(eventName, listener);
+		return 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, context) {
+		this.nc.settingsToListen(localSettings, context);
+	}
+	/** Augmente la limite Node.js (défaut 10) pour éviter le warning MaxListeners. */
+	setMaxListeners(n) {
+		this.nc.setMaxListeners(n);
+		return this;
+	}
+	/** Retire un listener spécifique et nettoie le tracking interne. */
+	removeListener(eventName, listener) {
+		this.nc.removeListener(eventName, listener);
+		this.untrackListener(eventName, listener);
+		return this;
+	}
+	/** Retire tous les listeners (ou ceux d'un événement précis si fourni). */
+	removeAllListeners(eventName) {
+		if (eventName !== void 0) {
+			this.#trackedListeners?.delete(eventName);
+			this.nc.removeAllListeners(eventName);
+		} else {
+			this.#trackedListeners = null;
+			this.nc.removeAllListeners();
+		}
+		return this;
+	}
+	/** Comme {@link once} mais inséré en tête de la liste des listeners. */
+	prependOnceListener(eventName, listener) {
+		this.nc.prependOnceListener(eventName, listener);
+		this.trackListener(eventName, listener);
+		return this;
+	}
+	/** Comme {@link on} mais inséré en tête de la liste des listeners. */
+	prependListener(eventName, listener) {
+		this.nc.prependListener(eventName, listener);
+		this.trackListener(eventName, listener);
+		return this;
+	}
+	/** Limite courante de listeners avant warning Node.js. */
+	getMaxListeners() {
+		return this.nc.getMaxListeners();
+	}
+	/** Nombre de listeners attachés à un événement (filtré sur `listener` si fourni). */
+	listenerCount(eventName, listener) {
+		return this.nc.listenerCount(eventName, listener);
+	}
+	/** Copie de la liste des listeners (résolus, sans le wrapper `once`). */
+	listeners(eventName) {
+		return this.nc.listeners(eventName);
+	}
+	/** Comme {@link listeners} mais retourne les wrappers Node.js bruts (avec once). */
+	rawListeners(eventName) {
+		return this.nc.rawListeners(eventName);
+	}
+	/** Récupère un service du DI container par nom. Retourne `null` si absent ou clean(). */
+	get(name) {
+		return this.container?.get(name) ?? null;
+	}
+	/**
+	* Enregistre un objet dans le DI container.
+	* @throws Error si `clean()` a déjà détaché le container.
+	*/
+	set(name, obj) {
+		if (!this.container) throw new Error(`${this.name}: container not initialized`);
+		this.container.set(name, obj);
+	}
+	/**
+	* 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) {
+		if (this.container) {
+			const ele = this.get(name);
+			if (ele) {
+				if (ele instanceof Service) ele.clean();
+				return this.container.remove(name);
+			}
+		}
+		return false;
+	}
+	/** Récupère un paramètre dynamique (config résolue) — `null` si absent. */
+	getParameters(name) {
+		return this.container?.getParameters(name) ?? null;
+	}
+	/**
+	* Définit un paramètre dynamique dans le container.
+	* @throws Error si `clean()` a déjà détaché le container.
+	*/
+	setParameters(name, ele) {
+		if (!this.container) throw new Error(`${this.name}: container not initialized`);
+		return this.container.setParameters(name, ele);
+	}
+	/** Vérifie l'existence d'un service ou paramètre dans le container. */
+	has(name) {
+		return this.container?.has(name) ?? false;
+	}
+};
+//#endregion
+export { Service as default };

package/dist/client/Tools.js

@@ -0,0 +1,162 @@
+import Container from "./Container.js";
+//#region src/Tools.ts
+const ObjProto = Object.prototype;
+const _toString = ObjProto.toString;
+const hasOwn = ObjProto.hasOwnProperty;
+const fnToString = hasOwn.toString;
+const ObjectFunctionString = fnToString.call(Object);
+const getProto = Object.getPrototypeOf;
+/** Alias direct de `Array.isArray` — exporté pour usage cohérent dans les modules. */
+const isArray = Array.isArray;
+/**
+* Type guard — `true` si `value` est une fonction (incluant arrow et classes).
+*
+* @param value - valeur inconnue à tester.
+*/
+const isFunction = (value) => typeof value === "function";
+/**
+* Type guard — `true` si `value` est une instance `RegExp`.
+*
+* @param value - valeur inconnue à tester.
+*/
+const isRegExp = (value) => value instanceof RegExp;
+/**
+* Vérifie qu'un objet est un "plain object" — `{}` ou `Object.create(null)`.
+*
+* Rejette les instances de classes, les `Array`, `Date`, `RegExp`, etc.
+* Implémentation alignée sur jQuery.isPlainObject (compatible cross-realm).
+*
+* @param obj - valeur à tester.
+* @returns `true` si l'objet vient directement de `Object` ou n'a pas de prototype.
+*/
+const isPlainObject = (obj) => {
+	if (!obj || _toString.call(obj) !== "[object Object]") return false;
+	const proto = getProto(obj);
+	if (!proto) return true;
+	const Ctor = hasOwn.call(proto, "constructor") && proto.constructor;
+	return typeof Ctor === "function" && fnToString.call(Ctor) === ObjectFunctionString;
+};
+/**
+* Type guard — `true` si `value === undefined` (strict, jamais `null`).
+*
+* @param value - valeur à tester.
+*/
+const isUndefined = (value) => value === void 0;
+/**
+* Vérifie qu'un objet existe et ne contient aucune clé propre énumérable.
+*
+* @param obj - objet à inspecter (peut être `null`/`undefined`).
+* @returns `true` si `obj` est défini ET `Object.keys(obj).length === 0`.
+*/
+const isEmptyObject = (obj) => !!obj && Object.keys(obj).length === 0;
+/**
+* Fusionne plusieurs objets dans une cible — API compatible `jQuery.extend`.
+*
+* Mode `shallow` (défaut) : copie les clés du dernier au premier source.
+* Mode `deep` (1er arg `true`) : récurse dans les plain objects et arrays.
+* Sécurité : ignore `__proto__`, `constructor`, `prototype` (anti prototype pollution).
+*
+* @param args - `[target, ...sources]` ou `[true, target, ...sources]` pour deep.
+* @returns la cible mutée (ou objet vide si appel à un seul argument).
+*
+* @example
+* ```ts
+* extend({ a: 1 }, { b: 2 });               // { a: 1, b: 2 }
+* extend(true, { a: { x: 1 } }, { a: { y: 2 } }); // { a: { x: 1, y: 2 } }
+* ```
+*/
+const extend = (...args) => {
+	let options, name, src, copy, copyIsArray = false, clone, target = args[0] || {}, i = 1, deep = false;
+	const { length } = args;
+	if (typeof target === "boolean") {
+		deep = target;
+		target = args[i] || {};
+		i++;
+	}
+	if (typeof target !== "object" && typeof target !== "function") target = {};
+	if (i === length) {
+		target = {};
+		i--;
+	}
+	for (; i < length; i++) if ((options = args[i]) != null) for (name in options) {
+		if (!hasOwn.call(options, name)) continue;
+		copy = options[name];
+		if (name === "__proto__" || name === "constructor" || name === "prototype" || target === copy) continue;
+		if (deep && copy && (isPlainObject(copy) || (copyIsArray = isArray(copy)))) {
+			src = target[name];
+			if (copyIsArray && !isArray(src)) clone = [];
+			else if (!copyIsArray && !isPlainObject(src)) clone = {};
+			else clone = src;
+			copyIsArray = false;
+			target[name] = extend(deep, clone, copy);
+		} else if (copy !== void 0) target[name] = copy;
+	}
+	return target;
+};
+/**
+* Détecte le type runtime d'une valeur — extension typée de `typeof`.
+*
+* Retourne `"buffer" | "array" | "date" | "RegExp" | "arguments" | "SyntaxError" | "Error"`
+* pour les objets connus, sinon le `typeof` natif. `null` pour `null`.
+*
+* @param value - valeur quelconque à classifier.
+* @returns string descriptive du type, ou `null` si valeur `null`.
+*
+* @example
+* ```ts
+* typeOf([]);              // "array"
+* typeOf(new Date());      // "date"
+* typeOf(Buffer.alloc(0)); // "buffer"
+* typeOf(null);            // null
+* ```
+*/
+const _gBuffer = globalThis.Buffer;
+const typeOf = (value) => {
+	const t = typeof value;
+	if (t === "object") {
+		if (value === null) return null;
+		if (_gBuffer?.isBuffer(value)) return "buffer";
+		if (isArray(value)) return "array";
+		if (value instanceof Date) return "date";
+		if (isRegExp(value)) return "RegExp";
+		if (Object.prototype.toString.call(value) === "[object Arguments]") return "arguments";
+		if (value instanceof SyntaxError) return "SyntaxError";
+		if (isError(value)) return "Error";
+	} else if (t === "function" && typeof value.call === "undefined") return "object";
+	return t;
+};
+/**
+* Type guard — `true` si la valeur est une instance de `Container` (DI).
+*
+* @param container - valeur à tester.
+*/
+const isContainer = (container) => container instanceof Container;
+/**
+* Type guard — `true` si la valeur est une instance d'`Error` natif.
+*
+* @param it - valeur à tester.
+*/
+const isError = (it) => it instanceof Error;
+/**
+* Vérifie qu'une valeur est une `Promise` ou un thenable (duck-typing `.then`).
+*
+* Accepte les promesses natives ET les bibliothèques tierces (Bluebird, etc.)
+* qui implémentent le protocole Promises/A+.
+*
+* @param obj - valeur à tester.
+* @returns `true` si `obj instanceof Promise` ou `typeof obj.then === "function"`.
+*/
+const isPromise = (obj) => {
+	if (obj instanceof Promise) return true;
+	return Boolean(obj) && (typeof obj === "object" || typeof obj === "function") && typeof obj.then === "function";
+};
+/**
+* Vérifie qu'une classe hérite (directement ou non) d'une autre.
+*
+* @param subclass - classe enfant supposée.
+* @param superclass - classe parent attendue.
+* @returns `true` si `subclass.prototype instanceof superclass`.
+*/
+const isSubclassOf = (subclass, superclass) => subclass.prototype instanceof superclass;
+//#endregion
+export { extend, isArray, isContainer, isEmptyObject, isFunction, isPlainObject, isPromise, isRegExp, isSubclassOf, isUndefined, typeOf };