@fraqjs/fraq 0.1.0 → 0.2.0

package/README.md

@@ -1,3 +1,59 @@
 # 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.create({
+  connect: {
+    baseUrl: '<替换成你的 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

@@ -5526,13 +5526,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 +5559,35 @@ 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 {
+  connect: {
+    baseUrl: string;
+    accessToken?: string;
+    initialReconnectDelay?: number;
+    maxReconnectDelay?: number;
+  };
+  logHandler?: (message: LogMessage) => void;
+}
 declare class Context {
   readonly client: MilkyClient;
-  private readonly parent?;
   readonly router: Router;
+  readonly logger: Logger;
+  private readonly parent?;
   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;
@@ -5567,21 +5600,12 @@ declare class Context {
   start(): Promise<void>;
   private applyPlugins;
   private sortPlugins;
-  private validateUniqueProvidedServices;
   private collectAvailableServices;
-  private areRequirementsAvailable;
   private createUnresolvablePluginError;
-  private describePlugin;
+  private createProxyContextForPlugin;
   private connectEventWebSocket;
-  private handleWebSocketMessage;
-  private delay;
   private createSession;
-  static create(options: {
-    connect: {
-      baseUrl: string;
-      accessToken?: string;
-    };
-  }): Context;
+  static create(options: ContextOptions): Context;
 }
 //#endregion
 //#region src/protocol/segment.d.ts
@@ -5625,24 +5649,27 @@ declare namespace seg {
 }
 //#endregion
 export {
-  type ApiEndpoints,
+  ApiEndpoints,
   Context,
-  type EventMap,
-  type Filter,
-  type MilkyClient,
+  ContextOptions,
+  EventMap,
+  Filter,
+  LogMessage,
+  Logger,
+  MilkyClient,
   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

@@ -246,25 +246,63 @@ 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 = new Logger((message) => this.logHandler?.(message), "context");
+	parent;
 	eventBus = mitt();
 	plugins = [];
 	services = /* @__PURE__ */ new Map();
 	subContexts = [];
+	initialReconnectDelayMs;
+	maxReconnectDelayMs;
+	logHandler;
 	isStarted = false;
-	constructor(client, parent, filter) {
+	constructor(client, options, parent, filter) {
 		this.client = client;
+		this.initialReconnectDelayMs = options?.connect.initialReconnectDelay ?? DEFAULT_INITIAL_RECONNECT_DELAY_MS;
+		this.maxReconnectDelayMs = options?.connect.maxReconnectDelay ?? DEFAULT_MAX_RECONNECT_DELAY_MS;
+		this.logHandler = options?.logHandler ?? parent?.logHandler;
 		this.parent = parent;
 		parent?.eventBus.on("*", (type, event) => {
 			if (filter) {
@@ -313,7 +351,7 @@ var Context = class Context {
 		return this.tryResolve(service) !== void 0;
 	}
 	fork(filter) {
-		const subContext = new Context(this.client, this, filter);
+		const subContext = new Context(this.client, void 0, this, filter);
 		this.subContexts.push(subContext);
 		return subContext;
 	}
@@ -327,18 +365,23 @@ var Context = class Context {
 	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.`);
+			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.`);
 		}
 	}
 	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 +389,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 +404,43 @@ 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;
+		let reconnectDelay = this.initialReconnectDelayMs;
 		while (this.isStarted) {
 			try {
-				const ws = await this.client.openEventWebSocket((event) => this.handleWebSocketMessage(event));
-				reconnectDelay = INITIAL_RECONNECT_DELAY_MS;
+				const ws = await this.client.openEventWebSocket((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);
+					}
+				});
+				reconnectDelay = this.initialReconnectDelayMs;
 				await new Promise((resolve) => {
 					ws.addEventListener("close", () => resolve(), { once: true });
 				});
 			} catch (error) {
 				console.error("Error connecting event WebSocket:", 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,
@@ -436,7 +467,7 @@ var Context = class Context {
 		};
 	}
 	static create(options) {
-		return new Context(createMilkyClient(options.connect.baseUrl, { accessToken: options.connect.accessToken }));
+		return new Context(createMilkyClient(options.connect.baseUrl, { accessToken: options.connect.accessToken }), options);
 	}
 };
 //#endregion
@@ -476,7 +507,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 +519,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 +805,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.2.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"