@fraqjs/fraq 0.5.1 → 0.6.1

package/dist/index.d.mts

@@ -5620,6 +5620,11 @@ declare function combineLogHandlers(...handlers: LogHandler[]): LogHandler;
 //#region src/core/service.d.ts
 /** biome-ignore-all lint/suspicious/noExplicitAny: Service constructors may accept any arguments. */
 type ServiceClass<T extends object = object> = abstract new (...args: any[]) => T;
+interface Disposable {
+  dispose(): void | Promise<void>;
+}
+declare function isDisposable(service: object): service is Disposable;
+declare function implementsESNextDisposable(service: object): boolean;
 //#endregion
 //#region src/core/plugin.d.ts
 type ParameterList = Array<any>;
@@ -5671,12 +5676,19 @@ declare class Context {
   private readonly plugins;
   private readonly services;
   private readonly subContexts;
+  private readonly parentEventForwarder?;
   private readonly initialReconnectDelayMs;
   private readonly maxReconnectDelayMs;
   private readonly logHandler?;
-  private isStarted;
+  private state;
+  private startPromise?;
+  private stopPromise?;
+  private eventSubscription?;
+  private eventStreamTask?;
+  private reconnectTimer?;
+  private resolveReconnectTimer?;
   private constructor();
-  on<K extends keyof EventMap>(type: K, handler: (event: EventMap[K]) => void | Promise<void>): void;
+  on<K extends keyof EventMap>(type: K, handler: (event: EventMap[K]) => void | Promise<void>): () => void;
   install<T extends ParameterList, I extends Injection | undefined, OI extends Injection | undefined>(
     plugin: Plugin<T, I, OI>,
     ...args: T
@@ -5688,6 +5700,11 @@ declare class Context {
   fork(name: string, filter?: Filter): Context;
   createSession(message: IncomingMessage): Session;
   start(): Promise<void>;
+  stop(): Promise<void>;
+  private startInternal;
+  private getState;
+  private stopInternal;
+  private stopEventStream;
   private acceptsParentEvent;
   private applyPlugins;
   private sortPlugins;
@@ -5698,6 +5715,8 @@ declare class Context {
   private createUnresolvablePluginError;
   private createProxyContextForPlugin;
   private runEventStream;
+  private waitForReconnectDelay;
+  private resolveReconnectDelay;
   static fromUrl(baseUrl: string | URL, options?: ContextOptions & ContextUrlOptions): Context;
   static fromClient(client: MilkyClient, options?: ContextOptions): Context;
 }
@@ -5748,6 +5767,7 @@ export {
   Context,
   ContextOptions,
   ContextUrlOptions,
+  Disposable,
   EventMap,
   Filter,
   Handler,
@@ -5768,13 +5788,15 @@ export {
   RouteEntry,
   RouteMatchResult,
   Router,
-  type ServiceClass,
+  ServiceClass,
   Session,
   SessionPredicate,
   combineLogHandlers,
   createMilkyClient,
   definePlugin,
   filter,
+  implementsESNextDisposable,
+  isDisposable,
   type types_d_exports as milky,
   milkyPackageVersion,
   milkyVersion,

package/dist/index.mjs

@@ -360,8 +360,11 @@ function combineLogHandlers(...handlers) {
 }
 //#endregion
 //#region src/core/service.ts
-function getServiceName(service) {
-	return service.name || "<anonymous service>";
+function isDisposable(service) {
+	return "dispose" in service && typeof service.dispose === "function";
+}
+function implementsESNextDisposable(service) {
+	return Symbol.dispose in service && typeof service[Symbol.dispose] === "function";
 }
 //#endregion
 //#region src/core/context.ts
@@ -378,10 +381,17 @@ var Context = class Context {
 	plugins = [];
 	services = /* @__PURE__ */ new Map();
 	subContexts = [];
+	parentEventForwarder;
 	initialReconnectDelayMs;
 	maxReconnectDelayMs;
 	logHandler;
-	isStarted = false;
+	state = "idle";
+	startPromise;
+	stopPromise;
+	eventSubscription;
+	eventStreamTask;
+	reconnectTimer;
+	resolveReconnectTimer;
 	constructor(client, options, name, parent, filter) {
 		this.client = client;
 		this.initialReconnectDelayMs = options?.reconnect?.initialDelayMs ?? DEFAULT_INITIAL_RECONNECT_DELAY_MS;
@@ -391,12 +401,16 @@ var Context = class Context {
 		this.logger = new Logger((message) => this.logHandler?.(message), this.name);
 		this.parent = parent;
 		this.filter = filter;
-		parent?.eventBus.on("*", (type, event) => {
-			if (!this.acceptsParentEvent(type, event)) return;
-			this.eventBus.emit(type, event);
-		});
+		if (parent) {
+			this.parentEventForwarder = (type, event) => {
+				if (!this.acceptsParentEvent(type, event)) return;
+				this.eventBus.emit(type, event);
+			};
+			parent.eventBus.on("*", this.parentEventForwarder);
+		}
 		this.eventBus.on("message_receive", async ({ data: message }) => {
 			try {
+				if (this.state === "stopping" || this.state === "stopped") return;
 				await this.router.dispatch(this.createSession(message), message);
 			} catch (error) {
 				this.logger.error(`Error routing command (scene=${message.message_scene} peer=${message.peer_id} sender=${message.sender_id} seq=${message.message_seq})`, error);
@@ -404,13 +418,18 @@ var Context = class Context {
 		});
 	}
 	on(type, handler) {
-		this.eventBus.on(type, async (event) => {
+		const wrappedHandler = async (event) => {
 			try {
+				if (this.state === "stopping" || this.state === "stopped") return;
 				await handler(event);
 			} catch (error) {
 				this.logger.error(`Error handling event ${type}`, error);
 			}
-		});
+		};
+		this.eventBus.on(type, wrappedHandler);
+		return () => {
+			this.eventBus.off(type, wrappedHandler);
+		};
 	}
 	install(plugin, ...args) {
 		this.plugins.push({
@@ -419,12 +438,20 @@ var Context = class Context {
 		});
 	}
 	provide(service, instance) {
-		if (this.services.has(service)) throw new Error(`Service ${getServiceName(service)} has already been provided in this context.`);
+		if (this.services.has(service)) throw new Error(`Service ${service.name} has already been provided in this context.`);
+		if (implementsESNextDisposable(instance) && !isDisposable(instance)) throw new Error(`
+Service ${service.name} implements ESNext Disposable but not Fraq Disposable.
+Please explicitly import the interface like this:
+
+import type { Disposable } from '@fraqjs/fraq';
+
+and implement the dispose method to clean up resources when the context stops.
+    `.trim());
 		this.services.set(service, instance);
 	}
 	resolve(service) {
 		const instance = this.tryResolve(service);
-		if (instance === void 0) throw new Error(`Service ${getServiceName(service)} has not been provided.`);
+		if (instance === void 0) throw new Error(`Service ${service.name} has not been provided.`);
 		return instance;
 	}
 	tryResolve(service) {
@@ -465,11 +492,88 @@ var Context = class Context {
 		};
 	}
 	async start() {
-		if (this.isStarted) return;
-		await this.applyPlugins();
+		if (this.state === "started") return;
+		if (this.state === "starting") {
+			await this.startPromise;
+			return;
+		}
+		if (this.state === "stopping") throw new Error(`Context "${this.name}" cannot be started while it is stopping.`);
+		if (this.state === "stopped") throw new Error(`Context "${this.name}" cannot be restarted after it has been stopped.`);
+		this.state = "starting";
+		this.startPromise = this.startInternal();
+		try {
+			await this.startPromise;
+		} finally {
+			this.startPromise = void 0;
+		}
+	}
+	async stop() {
+		if (this.state === "idle" || this.state === "stopped") return;
+		if (this.state === "starting") await this.startPromise;
+		const stateAfterStart = this.getState();
+		if (stateAfterStart === "idle" || stateAfterStart === "stopped") return;
+		if (stateAfterStart === "stopping") {
+			await this.stopPromise;
+			return;
+		}
+		this.state = "stopping";
+		this.stopPromise = this.stopInternal();
+		try {
+			await this.stopPromise;
+		} finally {
+			this.state = "stopped";
+			this.stopPromise = void 0;
+		}
+	}
+	async startInternal() {
+		try {
+			await this.applyPlugins();
+		} catch (error) {
+			this.state = "idle";
+			throw error;
+		}
 		for (const subContext of this.subContexts) await subContext.start();
-		this.isStarted = true;
-		if (!this.parent) this.runEventStream();
+		this.state = "started";
+		if (!this.parent) this.eventStreamTask = this.runEventStream();
+	}
+	getState() {
+		return this.state;
+	}
+	async stopInternal() {
+		const errors = [];
+		await this.stopEventStream(errors);
+		for (const subContext of [...this.subContexts].reverse()) try {
+			await subContext.stop();
+		} catch (error) {
+			errors.push(error);
+		}
+		if (this.parent && this.parentEventForwarder) this.parent.eventBus.off("*", this.parentEventForwarder);
+		for (const service of [...this.services.values()].reverse()) {
+			if (!isDisposable(service)) continue;
+			try {
+				await service.dispose();
+			} catch (error) {
+				errors.push(error);
+			}
+		}
+		if (errors.length === 1) throw errors[0];
+		if (errors.length > 1) throw new AggregateError(errors, `Context "${this.name}" failed to stop cleanly.`);
+	}
+	async stopEventStream(errors) {
+		this.resolveReconnectDelay();
+		const subscription = this.eventSubscription;
+		if (subscription) try {
+			await subscription.stop();
+		} catch (error) {
+			errors.push(error);
+		}
+		if (this.eventStreamTask) try {
+			await this.eventStreamTask;
+		} catch (error) {
+			errors.push(error);
+		} finally {
+			this.eventStreamTask = void 0;
+		}
 	}
 	acceptsParentEvent(type, event) {
 		if (!this.filter) return true;
@@ -479,17 +583,16 @@ var Context = class Context {
 	async applyPlugins() {
 		for (const { plugin, args } of this.sortPlugins()) {
 			const providedBeforeApply = new Set(this.services.keys());
-			this.logger.info(`Applying plugin ${plugin.name}`);
+			this.logger.debug(`Applying plugin ${plugin.name}`);
 			await plugin.apply(this.createProxyContextForPlugin(plugin), ...args);
-			for (const service of plugin.provides ?? []) if (!this.services.has(service) || providedBeforeApply.has(service)) throw new Error(`${plugin.name} declares service ${getServiceName(service)} but did not provide it.`);
-			this.logger.debug(`Applied plugin ${plugin.name}`);
+			for (const service of plugin.provides ?? []) if (!this.services.has(service) || providedBeforeApply.has(service)) throw new Error(`${plugin.name} declares service ${service.name} but did not provide it.`);
 		}
 	}
 	sortPlugins() {
 		const providers = /* @__PURE__ */ new Map();
 		for (const { plugin } of this.plugins) for (const service of plugin.provides ?? []) {
 			const existingProvider = providers.get(service);
-			if (existingProvider) throw new Error(`Service ${getServiceName(service)} is declared by multiple plugins: ${existingProvider.name} and ${plugin.name}.`);
+			if (existingProvider) throw new Error(`Service ${service.name} is declared by multiple plugins: ${existingProvider.name} and ${plugin.name}.`);
 			providers.set(service, plugin);
 		}
 		const pending = [...this.plugins];
@@ -540,7 +643,7 @@ var Context = class Context {
 		const lines = [...missingRequirements].map(([service, plugins]) => {
 			const dependents = plugins.map((plugin) => plugin.name).join(", ");
 			const reason = pendingProviders.has(service) ? "blocked by a dependency cycle" : "no installed plugin provides it";
-			return `${getServiceName(service)} required by ${dependents} (${reason})`;
+			return `${service.name} required by ${dependents} (${reason})`;
 		});
 		return /* @__PURE__ */ new Error(`Unable to resolve plugin service dependencies: ${lines.join("; ")}.`);
 	}
@@ -564,29 +667,58 @@ var Context = class Context {
 	async runEventStream() {
 		let reconnectDelay = this.initialReconnectDelayMs;
 		let reconnectAttempt = 1;
-		while (this.isStarted) {
+		while (this.state === "started") {
 			try {
 				this.logger.debug(`Connecting event stream (attempt=${reconnectAttempt})`);
 				const subscription = await this.client.startEvents((event) => {
 					try {
+						if (this.state !== "started") return;
 						this.eventBus.emit(event.event_type, event);
 					} catch (error) {
 						this.logger.error("Error handling event stream event", error);
 					}
 				});
+				if (this.state !== "started") {
+					await subscription.stop();
+					break;
+				}
+				this.eventSubscription = subscription;
 				this.logger.info("Event stream connected");
 				reconnectDelay = this.initialReconnectDelayMs;
 				reconnectAttempt = 1;
 				await subscription.closed;
+				this.eventSubscription = void 0;
+				if (this.state !== "started") break;
 				this.logger.warn(`Event stream disconnected; reconnecting in ${reconnectDelay}ms`);
 			} catch (error) {
+				this.eventSubscription = void 0;
+				if (this.state !== "started") break;
 				this.logger.error(`Error connecting event stream; reconnecting in ${reconnectDelay}ms`, error);
 			}
-			await new Promise((resolve) => setTimeout(resolve, reconnectDelay));
+			await this.waitForReconnectDelay(reconnectDelay);
 			reconnectDelay = Math.min(reconnectDelay * 2, this.maxReconnectDelayMs);
 			reconnectAttempt += 1;
 		}
 	}
+	waitForReconnectDelay(delay) {
+		return new Promise((resolve) => {
+			this.resolveReconnectTimer = resolve;
+			this.reconnectTimer = setTimeout(() => {
+				this.reconnectTimer = void 0;
+				this.resolveReconnectTimer = void 0;
+				resolve();
+			}, delay);
+		});
+	}
+	resolveReconnectDelay() {
+		if (this.reconnectTimer) {
+			clearTimeout(this.reconnectTimer);
+			this.reconnectTimer = void 0;
+		}
+		const resolve = this.resolveReconnectTimer;
+		this.resolveReconnectTimer = void 0;
+		resolve?.();
+	}
 	static fromUrl(baseUrl, options) {
 		return new Context(createMilkyClient(baseUrl, { accessToken: options?.accessToken }), options);
 	}
@@ -966,4 +1098,4 @@ let param;
 	_param.segment = segment;
 })(param || (param = {}));
 //#endregion
-export { Context, Logger, Parameter, Router, combineLogHandlers, createMilkyClient, definePlugin, filter, milkyPackageVersion, milkyVersion, msg, param, seg };
+export { Context, Logger, Parameter, Router, combineLogHandlers, createMilkyClient, definePlugin, filter, implementsESNextDisposable, isDisposable, milkyPackageVersion, milkyVersion, msg, param, seg };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fraqjs/fraq",
   "type": "module",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "Milky Bot framework",
   "files": [
     "dist"