@fraqjs/fraq 0.1.0 → 0.3.0

package/README.md

@@ -1,3 +1,56 @@
 # Fraq
 
-- [官方网站](https://fraq.ntqqrev.org/)
+Fraq 是一个 [Milky](https://milky.ntqqrev.org/) 协议的聊天机器人框架，在协议之上提供了更方便的上下文、路由、消息构造、插件和服务依赖注入能力，让你可以用 TypeScript 更轻松地组织一个机器人应用。
+
+## 安装 Fraq
+
+可以通过任意的包管理器安装 Fraq：
+
+```bash
+npm install @fraqjs/fraq
+# or
+yarn add @fraqjs/fraq
+# or
+pnpm add @fraqjs/fraq
+```
+
+Fraq 需要在 Node.js 22+ 环境（或其他的支持 WebSocket API 的服务端 JS 环境）中运行。强烈建议使用 TypeScript 来编写 Fraq 代码，并使用 [tsx](https://www.npmjs.com/package/tsx) 来运行你的项目。
+
+## 第一个 Fraq 机器人
+
+我们从一个 Echo 机器人开始。首先，启动你的 Milky 协议端，并确认它监听的地址与端口。然后，在你的项目中创建一个 `index.ts` 文件，并添加以下代码：
+
+```typescript
+import { Context, msg, param } from '@fraqjs/fraq';
+
+const ctx = Context.fromUrl('<替换成你的 Milky 协议端地址>', {
+  // accessToken: '<如果你的 Milky 协议端配置了 token，请在这里添加>',
+});
+
+ctx.router.command(
+  'echo',
+  {
+    content: param.greedy(),
+  },
+  (session, { content }) => {
+    session.reply(msg`You said: ${content}`);
+  },
+);
+
+ctx.start();
+```
+
+在一切完成之后，用 `tsx` 执行你的 `index.ts` 文件：
+
+```bash
+npx tsx index.ts
+# 或 tsx index.ts, 如果你全局安装了 tsx
+```
+
+你可以在任何一个包含它的会话中发送 `echo Hello` 来测试它是否正常工作。
+
+## 下一步
+
+上面的例子只是 Fraq 的最小使用方式，你还可以继续了解如何构造更丰富的消息、定义更复杂的指令参数、编写可复用的插件等。
+
+完整文档请见 [fraq.ntqqrev.org](https://fraq.ntqqrev.org/)。

package/dist/index.d.mts

@@ -5396,21 +5396,27 @@ type EventMap = {
 };
 //#endregion
 //#region src/protocol/client.d.ts
+interface MilkyEventSubscription {
+  closed: Promise<void>;
+  stop(): void | Promise<void>;
+}
+interface MilkyClient extends ApiEndpoints {
+  startEvents(onEvent: (event: Event) => void | Promise<void>): Promise<MilkyEventSubscription>;
+}
 declare class MilkyClientBase {
   readonly baseUrl: string;
   readonly wsBaseUrl: string;
   private readonly accessToken?;
   private readonly baseHeaders;
   constructor(
-    baseUrl: string,
+    baseUrl: string | URL,
     options?: {
       accessToken?: string;
     },
   );
   callApi(endpoint: string, params?: unknown): Promise<unknown>;
-  openEventWebSocket(onEvent: (event: MessageEvent) => void): Promise<WebSocket>;
+  startEvents(onEvent: (event: Event) => void | Promise<void>): Promise<MilkyEventSubscription>;
 }
-type MilkyClient = MilkyClientBase & ApiEndpoints;
 declare function createMilkyClient(...params: ConstructorParameters<typeof MilkyClientBase>): MilkyClient;
 //#endregion
 //#region src/routing/tokenizer.d.ts
@@ -5526,13 +5532,32 @@ type Filter = { [K in keyof EventMap]?: (event: EventMap[K]) => boolean };
 declare namespace filter {
   function define(filter: Filter): Filter;
   function allPass(): Filter;
-  function friend(uinList: number[]): Filter;
-  function group(uinList: number[]): Filter;
+  function friend(...uinList: number[]): Filter;
+  function group(...uinList: number[]): Filter;
   function admin(): Filter;
   function or(...filters: Filter[]): Filter;
   function and(...filters: Filter[]): Filter;
 }
 //#endregion
+//#region src/core/logging.d.ts
+interface LogMessage {
+  level: 'debug' | 'info' | 'warn' | 'error';
+  module: string;
+  message: string;
+  error?: unknown;
+  time: number;
+}
+declare class Logger {
+  private readonly logHandler;
+  private readonly module;
+  constructor(logHandler: (message: LogMessage) => void, module: string);
+  private log;
+  debug(message: string): void;
+  info(message: string): void;
+  warn(message: string, error?: unknown): void;
+  error(message: string, error?: unknown): void;
+}
+//#endregion
 //#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;
@@ -5540,21 +5565,38 @@ type ServiceClass<T extends object = object> = abstract new (...args: any[]) =>
 //#region src/core/plugin.d.ts
 type ParameterList = Array<any>;
 interface Plugin<T extends ParameterList> {
+  name: string;
   requires?: readonly ServiceClass[];
   provides?: readonly ServiceClass[];
-  apply(context: Context, ...args: T): void | Promise<void>;
+  apply(ctx: Context, ...args: T): void | Promise<void>;
 }
 declare function definePlugin<T extends ParameterList>(plugin: Plugin<T>): Plugin<T>;
 //#endregion
 //#region src/core/context.d.ts
+interface ContextOptions {
+  reconnect?: {
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+  };
+  logHandler?: (message: LogMessage) => void;
+}
+interface ContextUrlOptions {
+  accessToken?: string;
+}
 declare class Context {
   readonly client: MilkyClient;
-  private readonly parent?;
   readonly router: Router;
+  readonly logger: Logger;
+  readonly name: string;
+  private readonly parent?;
+  private readonly filter?;
   private readonly eventBus;
   private readonly plugins;
   private readonly services;
   private readonly subContexts;
+  private readonly initialReconnectDelayMs;
+  private readonly maxReconnectDelayMs;
+  private readonly logHandler?;
   private isStarted;
   private constructor();
   on<K extends keyof EventMap>(type: K, handler: (event: EventMap[K]) => void | Promise<void>): void;
@@ -5563,25 +5605,18 @@ declare class Context {
   resolve<T extends object>(service: ServiceClass<T>): T;
   tryResolve<T extends object>(service: ServiceClass<T>): T | undefined;
   isProvided<T extends object>(service: ServiceClass<T>): boolean;
-  fork(filter?: Filter): Context;
+  fork(name: string, filter?: Filter): Context;
   start(): Promise<void>;
+  private acceptsParentEvent;
   private applyPlugins;
   private sortPlugins;
-  private validateUniqueProvidedServices;
   private collectAvailableServices;
-  private areRequirementsAvailable;
   private createUnresolvablePluginError;
-  private describePlugin;
-  private connectEventWebSocket;
-  private handleWebSocketMessage;
-  private delay;
+  private createProxyContextForPlugin;
+  private runEventStream;
   private createSession;
-  static create(options: {
-    connect: {
-      baseUrl: string;
-      accessToken?: string;
-    };
-  }): Context;
+  static fromUrl(baseUrl: string | URL, options?: ContextOptions & ContextUrlOptions): Context;
+  static fromClient(client: MilkyClient, options?: ContextOptions): Context;
 }
 //#endregion
 //#region src/protocol/segment.d.ts
@@ -5625,24 +5660,29 @@ declare namespace seg {
 }
 //#endregion
 export {
-  type ApiEndpoints,
+  ApiEndpoints,
   Context,
-  type EventMap,
-  type Filter,
-  type MilkyClient,
+  ContextOptions,
+  ContextUrlOptions,
+  EventMap,
+  Filter,
+  LogMessage,
+  Logger,
+  MilkyClient,
+  MilkyEventSubscription,
   Parameter,
-  type ParameterList,
-  type Plugin,
+  ParameterList,
+  Plugin,
   Router,
   type ServiceClass,
-  type Session,
+  Session,
   createMilkyClient,
   definePlugin,
   filter,
+  type types_d_exports as milky,
   milkyPackageVersion,
   milkyVersion,
   msg,
   param,
   seg,
-  type types_d_exports as types,
 };

package/dist/index.mjs

@@ -6,7 +6,8 @@ var MilkyClientBase = class {
 	accessToken;
 	baseHeaders;
 	constructor(baseUrl, options) {
-		this.baseUrl = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+		const normalizedBaseUrl = baseUrl.toString();
+		this.baseUrl = normalizedBaseUrl.endsWith("/") ? normalizedBaseUrl.slice(0, -1) : normalizedBaseUrl;
 		this.wsBaseUrl = this.baseUrl.replace(/^http/, "ws");
 		this.accessToken = options?.accessToken;
 		this.baseHeaders = { "Content-Type": "application/json" };
@@ -18,18 +19,41 @@ var MilkyClientBase = class {
 			body: JSON.stringify(params ?? {}),
 			headers: this.baseHeaders
 		});
-		if (!response.ok) throw new Error(`API call failed with status ${response.status}`);
+		if (!response.ok) throw new Error(`API call ${endpoint} failed with HTTP status ${response.status}`);
 		const json = await response.json();
-		if (json.status === "failed") throw new Error(`API call failed with retcode ${json.retcode}: ${json.message}`);
+		if (json.status === "failed") throw new Error(`API call ${endpoint} failed with retcode ${json.retcode}: ${json.message}`);
 		return json.data;
 	}
-	async openEventWebSocket(onEvent) {
+	async startEvents(onEvent) {
 		const ws = new WebSocket(`${this.wsBaseUrl}/event${this.accessToken ? `?access_token=${this.accessToken}` : ""}`);
-		ws.addEventListener("message", onEvent);
-		return new Promise((resolve, reject) => {
-			ws.addEventListener("open", () => resolve(ws));
+		let closeSubscription = () => {};
+		const closed = new Promise((resolve, reject) => {
+			closeSubscription = (error) => {
+				if (error) reject(error);
+				else resolve();
+			};
+		});
+		ws.addEventListener("message", async (event) => {
+			try {
+				if (typeof event.data !== "string") throw new Error(`Expected text frame, got ${typeof event.data}`);
+				await onEvent(JSON.parse(event.data));
+			} catch (error) {
+				closeSubscription(error);
+				ws.close();
+			}
+		});
+		await new Promise((resolve, reject) => {
+			ws.addEventListener("open", () => resolve(), { once: true });
 			ws.addEventListener("error", (event) => reject(/* @__PURE__ */ new Error(`WebSocket error: ${event}`)));
 		});
+		ws.addEventListener("error", (event) => closeSubscription(/* @__PURE__ */ new Error(`WebSocket error: ${event}`)));
+		ws.addEventListener("close", () => closeSubscription(), { once: true });
+		return {
+			closed,
+			stop() {
+				ws.close();
+			}
+		};
 	}
 };
 function createMilkyClient(...params) {
@@ -246,38 +270,78 @@ var Router = class Router {
 	}
 };
 //#endregion
+//#region src/core/logging.ts
+var Logger = class {
+	logHandler;
+	module;
+	constructor(logHandler, module) {
+		this.logHandler = logHandler;
+		this.module = module;
+	}
+	log(level, message, error) {
+		this.logHandler({
+			level,
+			module: this.module,
+			message,
+			error,
+			time: Date.now()
+		});
+	}
+	debug(message) {
+		this.log("debug", message);
+	}
+	info(message) {
+		this.log("info", message);
+	}
+	warn(message, error) {
+		this.log("warn", message, error);
+	}
+	error(message, error) {
+		this.log("error", message, error);
+	}
+};
+//#endregion
 //#region src/core/service.ts
 function getServiceName(service) {
 	return service.name || "<anonymous service>";
 }
 //#endregion
 //#region src/core/context.ts
-const INITIAL_RECONNECT_DELAY_MS = 1e3;
-const MAX_RECONNECT_DELAY_MS = 3e4;
+const DEFAULT_INITIAL_RECONNECT_DELAY_MS = 1e3;
+const DEFAULT_MAX_RECONNECT_DELAY_MS = 3e4;
 var Context = class Context {
 	client;
-	parent;
 	router = new Router();
+	logger;
+	name;
+	parent;
+	filter;
 	eventBus = mitt();
 	plugins = [];
 	services = /* @__PURE__ */ new Map();
 	subContexts = [];
+	initialReconnectDelayMs;
+	maxReconnectDelayMs;
+	logHandler;
 	isStarted = false;
-	constructor(client, parent, filter) {
+	constructor(client, options, name, parent, filter) {
 		this.client = client;
+		this.initialReconnectDelayMs = options?.reconnect?.initialDelayMs ?? DEFAULT_INITIAL_RECONNECT_DELAY_MS;
+		this.maxReconnectDelayMs = options?.reconnect?.maxDelayMs ?? DEFAULT_MAX_RECONNECT_DELAY_MS;
+		this.logHandler = options?.logHandler ?? parent?.logHandler;
+		this.name = name ?? "root";
+		this.logger = new Logger((message) => this.logHandler?.(message), this.name);
 		this.parent = parent;
+		this.filter = filter;
 		parent?.eventBus.on("*", (type, event) => {
-			if (filter) {
-				const predicate = filter[type];
-				if (predicate && !predicate(event)) return;
-			}
+			if (!this.acceptsParentEvent(type, event)) return;
 			this.eventBus.emit(type, event);
 		});
 		this.eventBus.on("message_receive", async ({ data: message }) => {
 			try {
-				this.router.dispatch(this.createSession(message), message);
+				await this.router.dispatch(this.createSession(message), message);
 			} catch (error) {
-				console.error("Error routing command:", error);
+				this.logger.error(`Error routing command (scene=${message.message_scene} peer=${message.peer_id} sender=${message.sender_id} seq=${message.message_seq})`, error);
 			}
 		});
 	}
@@ -286,7 +350,7 @@ var Context = class Context {
 			try {
 				await handler(event);
 			} catch (error) {
-				console.error(`Error handling event ${type}:`, error);
+				this.logger.error(`Error handling event ${type}`, error);
 			}
 		});
 	}
@@ -312,8 +376,8 @@ var Context = class Context {
 	isProvided(service) {
 		return this.tryResolve(service) !== void 0;
 	}
-	fork(filter) {
-		const subContext = new Context(this.client, this, filter);
+	fork(name, filter) {
+		const subContext = new Context(this.client, void 0, name, this, filter);
 		this.subContexts.push(subContext);
 		return subContext;
 	}
@@ -322,23 +386,35 @@ var Context = class Context {
 		await this.applyPlugins();
 		for (const subContext of this.subContexts) await subContext.start();
 		this.isStarted = true;
-		if (!this.parent) this.connectEventWebSocket();
+		if (!this.parent) this.runEventStream();
+	}
+	acceptsParentEvent(type, event) {
+		if (!this.filter) return true;
+		const predicate = this.filter[type];
+		return predicate?.(event) === true;
 	}
 	async applyPlugins() {
 		for (const { plugin, args } of this.sortPlugins()) {
 			const providedBeforeApply = new Set(this.services.keys());
-			await plugin.apply(this, ...args);
-			for (const service of plugin.provides ?? []) if (!this.services.has(service) || providedBeforeApply.has(service)) throw new Error(`${this.describePlugin(plugin)} declares service ${getServiceName(service)} but did not provide it.`);
+			this.logger.info(`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}`);
 		}
 	}
 	sortPlugins() {
-		this.validateUniqueProvidedServices();
+		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}.`);
+			providers.set(service, plugin);
+		}
 		const pending = [...this.plugins];
 		const sorted = [];
 		const available = /* @__PURE__ */ new Set();
 		for (const service of this.collectAvailableServices()) available.add(service);
 		while (pending.length > 0) {
-			const nextIndex = pending.findIndex(({ plugin }) => this.areRequirementsAvailable(plugin, available));
+			const nextIndex = pending.findIndex(({ plugin }) => (plugin.requires ?? []).every((service) => available.has(service)));
 			if (nextIndex === -1) throw this.createUnresolvablePluginError(pending, available);
 			const [next] = pending.splice(nextIndex, 1);
 			sorted.push(next);
@@ -346,22 +422,11 @@ var Context = class Context {
 		}
 		return sorted;
 	}
-	validateUniqueProvidedServices() {
-		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: ${this.describePlugin(existingProvider)} and ${this.describePlugin(plugin)}.`);
-			providers.set(service, plugin);
-		}
-	}
 	collectAvailableServices() {
 		const services = [...this.services.keys()];
 		if (this.parent) services.push(...this.parent.collectAvailableServices());
 		return services;
 	}
-	areRequirementsAvailable(plugin, available) {
-		return (plugin.requires ?? []).every((service) => available.has(service));
-	}
 	createUnresolvablePluginError(pending, available) {
 		const missingRequirements = /* @__PURE__ */ new Map();
 		const pendingProviders = /* @__PURE__ */ new Set();
@@ -372,44 +437,39 @@ var Context = class Context {
 			missingRequirements.set(service, plugins);
 		}
 		const lines = [...missingRequirements].map(([service, plugins]) => {
-			const dependents = plugins.map((plugin) => this.describePlugin(plugin)).join(", ");
+			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 /* @__PURE__ */ new Error(`Unable to resolve plugin service dependencies: ${lines.join("; ")}.`);
 	}
-	describePlugin(plugin) {
-		const pluginIndex = this.plugins.findIndex((installed) => installed.plugin === plugin);
-		return plugin.constructor.name && plugin.constructor.name !== "Object" ? plugin.constructor.name : `plugin #${pluginIndex + 1}`;
+	createProxyContextForPlugin(plugin) {
+		const proxyLogger = new Logger((message) => this.logHandler?.(message), plugin.name);
+		return new Proxy(this, { get(target, prop) {
+			if (prop === "logger") return proxyLogger;
+			else return target[prop];
+		} });
 	}
-	async connectEventWebSocket() {
-		let reconnectDelay = INITIAL_RECONNECT_DELAY_MS;
+	async runEventStream() {
+		let reconnectDelay = this.initialReconnectDelayMs;
 		while (this.isStarted) {
 			try {
-				const ws = await this.client.openEventWebSocket((event) => this.handleWebSocketMessage(event));
-				reconnectDelay = INITIAL_RECONNECT_DELAY_MS;
-				await new Promise((resolve) => {
-					ws.addEventListener("close", () => resolve(), { once: true });
+				const subscription = await this.client.startEvents((event) => {
+					try {
+						this.eventBus.emit(event.event_type, event);
+					} catch (error) {
+						this.logger.error("Error handling event stream event", error);
+					}
 				});
+				reconnectDelay = this.initialReconnectDelayMs;
+				await subscription.closed;
 			} catch (error) {
-				console.error("Error connecting event WebSocket:", error);
+				this.logger.error("Error connecting event stream", error);
 			}
-			await this.delay(reconnectDelay);
-			reconnectDelay = Math.min(reconnectDelay * 2, MAX_RECONNECT_DELAY_MS);
+			await new Promise((resolve) => setTimeout(resolve, reconnectDelay));
+			reconnectDelay = Math.min(reconnectDelay * 2, this.maxReconnectDelayMs);
 		}
 	}
-	handleWebSocketMessage(event) {
-		try {
-			if (typeof event.data !== "string") throw new Error(`Expected text frame, got ${typeof event.data}`);
-			const payload = JSON.parse(event.data);
-			this.eventBus.emit(payload.event_type, payload);
-		} catch (error) {
-			console.error("Error handling WebSocket event:", error);
-		}
-	}
-	delay(ms) {
-		return new Promise((resolve) => setTimeout(resolve, ms));
-	}
 	createSession(message) {
 		return {
 			raw: message,
@@ -430,13 +490,16 @@ var Context = class Context {
 							break;
 					}
 				} catch (error) {
-					console.error("Error sending reply:", error);
+					this.logger.error(`Error sending reply (source msg: scene=${message.message_scene} peer=${message.peer_id} sender=${message.sender_id} seq=${message.message_seq})`, error);
 				}
 			}
 		};
 	}
-	static create(options) {
-		return new Context(createMilkyClient(options.connect.baseUrl, { accessToken: options.connect.accessToken }));
+	static fromUrl(baseUrl, options) {
+		return new Context(createMilkyClient(baseUrl, { accessToken: options?.accessToken }), options);
+	}
+	static fromClient(client, options) {
+		return new Context(client, options);
 	}
 };
 //#endregion
@@ -476,7 +539,7 @@ let filter;
 		return result;
 	}
 	_filter.allPass = allPass;
-	function friend(uinList) {
+	function friend(...uinList) {
 		const uinSet = new Set(uinList);
 		return {
 			message_receive: ({ data }) => data.message_scene === "friend" && uinSet.has(data.peer_id),
@@ -488,7 +551,7 @@ let filter;
 		};
 	}
 	_filter.friend = friend;
-	function group(uinList) {
+	function group(...uinList) {
 		const uinSet = new Set(uinList);
 		return {
 			message_receive: ({ data }) => data.message_scene === "group" && uinSet.has(data.peer_id),
@@ -774,4 +837,4 @@ let param;
 	_param.segment = segment;
 })(param || (param = {}));
 //#endregion
-export { Context, Parameter, Router, createMilkyClient, definePlugin, filter, milkyPackageVersion, milkyVersion, msg, param, seg };
+export { Context, Logger, Parameter, Router, createMilkyClient, definePlugin, filter, milkyPackageVersion, milkyVersion, msg, param, seg };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fraqjs/fraq",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Milky Bot framework",
   "files": [
     "dist"
@@ -14,6 +14,7 @@
     "type": "git",
     "url": "git+https://github.com/Wesley-Young/fraq.git"
   },
+  "homepage": "https://fraq.ntqqrev.org/",
   "license": "MIT",
   "dependencies": {
     "mitt": "^3.0.1"
@@ -22,7 +23,7 @@
     "node": ">=22"
   },
   "scripts": {
-    "build": "tsdown && node scripts/format-dts-comments.mjs && biome format --vcs-enabled=false --write dist/index.d.mts",
+    "build": "tsdown && tsx scripts/format-dts-comments.ts && biome format --vcs-enabled=false --write dist/index.d.mts",
     "test": "tsx --test test/*.test.ts"
   }
 }