@fraqjs/fraq 0.8.2 → 0.9.1

package/README.md

@@ -27,15 +27,12 @@ const ctx = Context.fromUrl('<替换成你的 Milky 协议端地址>', {
   // accessToken: '<如果你的 Milky 协议端配置了 token，请在这里添加>',
 });
 
-ctx.router.command({
-  name: 'echo',
-  pattern: {
-    content: param.greedy(),
-  },
-  execute(session, { content }) {
+ctx.router
+  .command('echo')
+  .arg('content', param.greedy())
+  .execute((session, { content }) => {
     session.reply(msg`You said: ${content}`);
-  },
-});
+  });
 
 ctx.start();
 ```

package/dist/index.d.mts

@@ -5506,20 +5506,54 @@ declare namespace param {
   >;
 }
 //#endregion
-//#region src/routing/router.d.ts
+//#region src/routing/command.d.ts
 type Pattern = Record<string, Parameter<any>>;
 type ParamsOf<P extends Pattern> = { [K in keyof P]: P[K] extends Parameter<infer T> ? T : never };
 type Executor<P extends Pattern> = (session: Session, params: ParamsOf<P>) => void | Promise<void>;
-type SessionPredicate = (session: Session) => boolean;
 interface Command<P extends Pattern> {
   name: string;
   pattern: P;
   execute: Executor<P>;
+  description?: string;
+  aliases?: string[];
+  hidden?: boolean;
 }
 interface RawPattern<P extends Pattern> {
   pattern: P;
   execute: Executor<P>;
 }
+interface Session {
+  raw: IncomingMessage;
+  reply(segments: OutgoingSegment_ZodInput[]): Promise<void>;
+}
+declare class CommandBuilder<P extends Pattern = {}, S = Command<P>> {
+  readonly name: string;
+  private readonly sink;
+  private readonly pattern;
+  private executor?;
+  private description?;
+  private aliases?;
+  private hidden?;
+  constructor(name: string, sink?: (command: Command<P>) => S);
+  arg<K extends string, T>(
+    key: K,
+    parameter: Parameter<T>,
+  ): CommandBuilder<
+    P & { [K2 in K]: Parameter<T> },
+    S extends Command<P>
+      ? Command<P & { [K2 in K]: Parameter<T> }>
+      : S extends RawPattern<P>
+        ? RawPattern<P & { [K2 in K]: Parameter<T> }>
+        : S
+  >;
+  describe(description: string): CommandBuilder<P, S>;
+  alias(...aliases: string[]): CommandBuilder<P, S>;
+  hide(): CommandBuilder<P, S>;
+  execute(executor: Executor<P>): S;
+}
+//#endregion
+//#region src/routing/router.d.ts
+type SessionPredicate = (session: Session) => boolean;
 type RouteEntry =
   | {
       type: 'command';
@@ -5563,18 +5597,17 @@ type RouteMatchResult =
       rawPattern: RawPattern<Pattern>;
       params: any;
     };
-interface Session {
-  raw: IncomingMessage;
-  reply(segments: OutgoingSegment_ZodInput[]): Promise<void>;
-}
 declare class Router {
   private readonly entries;
   private readonly groups;
+  command(name: string): CommandBuilder;
   command<P extends Pattern>(command: Command<P>): this;
+  rawPattern(): CommandBuilder<{}, RawPattern<{}>>;
   rawPattern<P extends Pattern>(rawPattern: RawPattern<P>): this;
   group(name: string): Router;
   filter(predicate: SessionPredicate): Router;
   routes(): RouteEntry[];
+  aliasesOf(name: string): string[];
   branches(session: Session): RouteBranch[];
   match(session: Session, message: IncomingMessage): RouteMatchResult | undefined;
   dispatch(session: Session, message: IncomingMessage): Promise<boolean>;
@@ -5584,6 +5617,7 @@ declare class Router {
   private matchGroup;
   private matchRawPattern;
   private branchesFrom;
+  private resolveAliasConflicts;
   private validatePattern;
   private capturePattern;
 }
@@ -5784,6 +5818,7 @@ export {
   ApiEndpoints,
   Capturer,
   Command,
+  CommandBuilder,
   Context,
   ContextOptions,
   ContextUrlOptions,

package/dist/index.mjs

@@ -64,6 +64,50 @@ function createMilkyClient(...params) {
 	} });
 }
 //#endregion
+//#region src/routing/command.ts
+var CommandBuilder = class {
+	name;
+	sink;
+	pattern = {};
+	executor;
+	description;
+	aliases;
+	hidden;
+	constructor(name, sink = (command) => command) {
+		this.name = name;
+		this.sink = sink;
+	}
+	arg(key, parameter) {
+		this.pattern[key] = parameter;
+		return this;
+	}
+	describe(description) {
+		this.description = description;
+		return this;
+	}
+	alias(...aliases) {
+		if (!this.aliases) this.aliases = [];
+		this.aliases.push(...aliases);
+		return this;
+	}
+	hide() {
+		this.hidden = true;
+		return this;
+	}
+	execute(executor) {
+		this.executor = executor;
+		const command = {
+			name: this.name,
+			pattern: this.pattern,
+			execute: this.executor
+		};
+		if (this.description !== void 0) command.description = this.description;
+		if (this.aliases !== void 0) command.aliases = this.aliases;
+		if (this.hidden !== void 0) command.hidden = this.hidden;
+		return this.sink(command);
+	}
+};
+//#endregion
 //#region src/routing/tokenizer.ts
 var Tokenizer = class {
 	segments;
@@ -192,7 +236,12 @@ var Router = class Router {
 	entries = [];
 	groups = /* @__PURE__ */ new Map();
 	command(command) {
+		if (typeof command === "string") return new CommandBuilder(command, (builtCommand) => {
+			this.command(builtCommand);
+			return builtCommand;
+		});
 		this.validatePattern(command.pattern);
+		this.resolveAliasConflicts(command);
 		this.entries.push({
 			type: "command",
 			command
@@ -200,6 +249,10 @@ var Router = class Router {
 		return this;
 	}
 	rawPattern(rawPattern) {
+		if (!rawPattern) return new CommandBuilder("", (builtCommand) => {
+			this.rawPattern(builtCommand);
+			return builtCommand;
+		});
 		this.validatePattern(rawPattern.pattern, { rawPattern: true });
 		this.entries.push({
 			type: "rawPattern",
@@ -232,6 +285,10 @@ var Router = class Router {
 	routes() {
 		return this.entries;
 	}
+	aliasesOf(name) {
+		for (const entry of this.entries) if (entry.type === "command" && entry.command.name === name) return entry.command.aliases ? [...entry.command.aliases] : [];
+		return [];
+	}
 	branches(session) {
 		return this.branchesFrom(session, []);
 	}
@@ -273,7 +330,7 @@ var Router = class Router {
 	}
 	matchCommand(command, tokenizer, path) {
 		const token = tokenizer.peek();
-		if (typeof token !== "string" || token !== command.name) return;
+		if (typeof token !== "string" || token !== command.name && !command.aliases?.includes(token)) return;
 		tokenizer.next();
 		const params = this.capturePattern(command.pattern, tokenizer);
 		if (params === void 0 || tokenizer.hasNext()) return;
@@ -304,7 +361,7 @@ var Router = class Router {
 		const branches = [];
 		for (const entry of this.entries) switch (entry.type) {
 			case "command":
-				branches.push({
+				if (!entry.command.hidden) branches.push({
 					type: "command",
 					path: [...path],
 					command: entry.command
@@ -326,6 +383,27 @@ var Router = class Router {
 		}
 		return branches;
 	}
+	resolveAliasConflicts(command) {
+		for (const entry of this.entries) {
+			if (entry.type !== "command") continue;
+			const existing = entry.command;
+			if (existing.aliases?.includes(command.name)) {
+				existing.aliases = existing.aliases.filter((a) => a !== command.name);
+				console.warn(`Command "${command.name}" conflicts with alias of existing command "${existing.name}". The alias "${command.name}" has been removed from "${existing.name}".`);
+			}
+			if (command.aliases) {
+				const dropped = [];
+				for (const alias of command.aliases) if (existing.name === alias) {
+					dropped.push(alias);
+					console.warn(`Alias "${alias}" of command "${command.name}" conflicts with existing command name "${existing.name}". The alias has been dropped.`);
+				} else if (existing.aliases?.includes(alias)) {
+					existing.aliases = existing.aliases.filter((a) => a !== alias);
+					console.warn(`Alias "${alias}" of command "${command.name}" conflicts with alias of existing command "${existing.name}". The alias has been removed from "${existing.name}".`);
+				}
+				if (dropped.length > 0) command.aliases = command.aliases.filter((a) => !dropped.includes(a));
+			}
+		}
+	}
 	validatePattern(pattern, options) {
 		const entries = Object.entries(pattern);
 		if (options?.rawPattern && entries.length === 0) throw new Error("Raw pattern must have at least one parameter.");
@@ -648,7 +726,15 @@ and implement the dispose method to clean up resources when the context stops.
 		for (const installedPlugin of sortedPlugins) {
 			const { plugin, args } = installedPlugin;
 			const providedBeforeApply = new Set(this.services.keys());
-			this.logger.debug(`Applying plugin ${plugin.name}`);
+			let debugMessage = `Applying plugin ${plugin.name}`;
+			const requiredServices = [];
+			const providedServices = [];
+			if (plugin.requires) for (const service of plugin.requires) requiredServices.push(service.name);
+			if (plugin.optionalRequires) for (const service of plugin.optionalRequires) requiredServices.push(`${service.name}?`);
+			if (plugin.provides) for (const service of plugin.provides) providedServices.push(service.name);
+			if (requiredServices.length > 0) debugMessage += `, requires: [${requiredServices.join(", ")}]`;
+			if (providedServices.length > 0) debugMessage += `, provides: [${providedServices.join(", ")}]`;
+			this.logger.debug(debugMessage);
 			await plugin.apply(this.getPluginContext(installedPlugin), ...args);
 			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.`);
 		}
@@ -747,10 +833,6 @@ and implement the dispose method to clean up resources when the context stops.
 	}
 	createProxyContextForPlugin(plugin) {
 		const proxyLogger = new Logger((message) => this.logHandler?.(message), plugin.name);
-		const proxyProvide = (service, instance) => {
-			this.provide(service, instance);
-			this.logger.debug(`Plugin ${plugin.name} provided ${service.name}`);
-		};
 		let proxyInjections;
 		if (plugin.inject) {
 			proxyInjections = {};
@@ -762,7 +844,6 @@ and implement the dispose method to clean up resources when the context stops.
 		}
 		return new Proxy(this, { get(target, prop, receiver) {
 			if (prop === "logger") return proxyLogger;
-			else if (prop === "provide") return proxyProvide;
 			else if (proxyInjections && prop in proxyInjections) return proxyInjections[prop];
 			else return Reflect.get(target, prop, receiver);
 		} });
@@ -1230,4 +1311,4 @@ let param;
 	_param.segment = segment;
 })(param || (param = {}));
 //#endregion
-export { Context, Logger, Parameter, Router, combineLogHandlers, createMilkyClient, definePlugin, filter, implementsESNextDisposable, isDisposable, milkyPackageVersion, milkyVersion, msg, param, seg };
+export { CommandBuilder, 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.8.2",
+  "version": "0.9.1",
   "description": "Milky Bot framework",
   "files": [
     "dist"