nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/client/Container.js

@@ -0,0 +1,367 @@
+import { extend, isPlainObject } from "./Tools.js";
+//#region src/Container.ts
+const ISDefined = function(ele) {
+	return ele !== null && ele !== void 0;
+};
+const parseParameterString = function(str, value) {
+	if (!this) throw new Error(`Bad call`);
+	const parts = str.split(".");
+	const currentPart = parts.shift();
+	if (currentPart !== void 0) {
+		if (parts.length === 0) {
+			if (value !== void 0) this[currentPart] = value;
+			return this[currentPart] ?? null;
+		}
+		if (this[currentPart] === void 0 || this[currentPart] === null) {
+			if (value !== void 0) this[currentPart] = {};
+			else return null;
+		}
+		if (typeof this[currentPart] !== "object") throw new Error(`Cannot create property '${parts[0]}' on ${typeof this[currentPart]} '${this[currentPart]}'`);
+		return parseParameterString.call(this[currentPart], parts.join("."), value);
+	}
+	return this;
+};
+let containerSeq = 0;
+/**
+* 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.
+*/
+var Container = class Container {
+	protoService;
+	services;
+	protoParameters;
+	parameters;
+	id;
+	scopes = null;
+	/**
+	* Create a new container. When an existing container is passed in, the
+	* new instance inherits its services (via prototype chaining) and clones
+	* its parameters — used by {@link Scope} to build short-lived containers
+	* that share base services but isolate per-request state.
+	*
+	* @param input - parent container to inherit services from
+	* @param deep - if `true`, parameters are deep-cloned via `structuredClone`
+	* (falls back to shallow copy if `structuredClone` throws on unsupported types)
+	* @param adoptedProtoService - @internal canal {@link Scope} : adopte le
+	* proto-services du PARENT au lieu d'allouer une closure locale morte
+	* (2 closures + 2 `Object.create` jetés par requête avant ce chemin)
+	* @param adoptedProtoParameters - @internal idem pour les paramètres
+	*/
+	constructor(input, deep = false, adoptedProtoService, adoptedProtoParameters) {
+		this.id = (++containerSeq).toString(36);
+		this.protoService = adoptedProtoService ?? function() {};
+		this.protoParameters = adoptedProtoParameters ?? function() {};
+		if (input && input instanceof Container) {
+			this.services = Object.create(input.protoService.prototype);
+			this.parameters = Object.create(input.protoParameters.prototype);
+			this.setServices(input.services ?? {});
+			if (deep) try {
+				this.setParametersBulk(structuredClone(input.parameters ?? {}));
+			} catch {
+				this.setParametersBulk(input.parameters ?? {});
+			}
+			else this.setParametersBulk(input.parameters ?? {});
+		} else {
+			this.services = Object.create(this.protoService.prototype);
+			this.parameters = Object.create(this.protoParameters.prototype);
+		}
+	}
+	setServices(services) {
+		for (const service in services) this.set(service, services[service]);
+	}
+	setParametersBulk(parameters) {
+		for (const parameter in parameters) this.setParameters(parameter, parameters[parameter]);
+	}
+	/**
+	* 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, severity, msgid, msg) {
+		const syslog = this.get("syslog");
+		if (!syslog) {
+			console.warn(`[Container] no syslog registered —`, pci);
+			return;
+		}
+		if (!msgid) msgid = "SERVICES CONTAINER";
+		return syslog.log(pci, severity, msgid, msg);
+	}
+	/**
+	* 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(name, object) {
+		if (this.services && name) {
+			this.protoService.prototype[name] = object;
+			this.services[name] = object;
+		} else throw new Error("Container bad argument name");
+	}
+	/**
+	* 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(name) {
+		if (this.services && name in this.services) return this.services[name];
+		return 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) {
+		if (!this.services) return false;
+		if (name in this.services) {
+			delete this.services[name];
+			if (name in this.protoService.prototype) delete this.protoService.prototype[name];
+			if (this.scopes) for (const bucket of this.scopes.values()) for (const scope of bucket.values()) scope.remove(name);
+			return true;
+		}
+		return false;
+	}
+	/** Whether a service is registered under `name`. */
+	has(name) {
+		return this.services != null && name in this.services;
+	}
+	/** All service names currently registered on this container. */
+	keys() {
+		return Object.keys(this.services ?? {});
+	}
+	/** All `[name, service]` pairs currently registered on this container. */
+	entries() {
+		return Object.entries(this.services ?? {});
+	}
+	/**
+	* 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) {
+		if (this.scopes === null) this.scopes = /* @__PURE__ */ new Map();
+		let bucket = this.scopes.get(name);
+		if (!bucket) {
+			bucket = /* @__PURE__ */ new Map();
+			this.scopes.set(name, bucket);
+		}
+		return bucket;
+	}
+	/**
+	* 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) {
+		const bucket = this.scopes?.get(name);
+		if (!bucket) throw new Error(`Scope "${name}" not declared. Call addScope("${name}") first.`);
+		const sc = new Scope(name, this, this.protoService, this.protoParameters);
+		bucket.set(sc.id, sc);
+		return sc;
+	}
+	/**
+	* 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) {
+		const bucket = this.scopes?.get(scope.name);
+		if (bucket) {
+			const sc = bucket.get(scope.id);
+			if (sc) {
+				sc.clean();
+				bucket.delete(scope.id);
+			}
+		}
+	}
+	/**
+	* 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) {
+		return this.scopes?.get(name)?.size ?? 0;
+	}
+	/**
+	* 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) {
+		const bucket = this.scopes?.get(name);
+		if (bucket) {
+			for (const scope of bucket.values()) this.leaveScope(scope);
+			this.scopes?.delete(name);
+		}
+	}
+	removeAllScopes() {
+		if (!this.scopes) return;
+		for (const name of this.scopes.keys()) this.removeScope(name);
+		this.scopes = null;
+	}
+	/**
+	* 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(name, ele) {
+		if (typeof name !== "string") throw new Error("setParameters : container parameter name must be a string");
+		if (ele === void 0) throw new Error(`setParameters : ${name} container parameter value must be defined`);
+		if (!this.parameters) return null;
+		return parseParameterString.call(this.parameters, name, ele);
+	}
+	/**
+	* 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) {
+		if (!name) throw new Error(`getParameters : invalid name "${name}"`);
+		if (!this.parameters) return null;
+		return parseParameterString.call(this.parameters, name);
+	}
+	/**
+	* 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() {
+		this.removeAllScopes();
+		this.services = null;
+		this.parameters = null;
+	}
+	/**
+	* 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() {
+		this.clean();
+		this.protoService = function() {};
+		this.protoParameters = function() {};
+		this.services = Object.create(this.protoService.prototype);
+		this.parameters = Object.create(this.protoParameters.prototype);
+	}
+};
+/**
+* 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.
+*/
+var Scope = class extends Container {
+	name;
+	parent;
+	constructor(name, parent, parentProtoService, parentProtoParameters) {
+		super(void 0, false, parentProtoService, parentProtoParameters);
+		this.name = name;
+		this.parent = parent;
+	}
+	/**
+	* 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(name, object) {
+		if (this.services && name) this.services[name] = object;
+		else throw new Error("Container bad argument name");
+	}
+	/**
+	* 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) {
+		if (this.services && Object.prototype.hasOwnProperty.call(this.services, name)) {
+			delete this.services[name];
+			return true;
+		}
+		return false;
+	}
+	/**
+	* 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, merge = true, deep = true) {
+		const res = parseParameterString.call(this.parameters ?? {}, name);
+		const obj = this.parent?.getParameters(name);
+		if (ISDefined(res)) {
+			if (merge && isPlainObject(obj) && isPlainObject(res)) return extend(deep, obj, res);
+			return res;
+		}
+		return obj ?? 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() {
+		this.parent = null;
+		return super.clean();
+	}
+};
+//#endregion
+export { Scope, Container as default };

package/dist/client/Event.js

@@ -0,0 +1,198 @@
+import { EventEmitter } from "./client/shim/events.js";
+//#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 };