@fraqjs/fraq 0.3.3 → 0.5.0

package/dist/index.d.mts

@@ -5507,6 +5507,58 @@ type Pattern = Record<string, Parameter<any>>;
 type ParamsOf<P extends Pattern> = { [K in keyof P]: P[K] extends Parameter<infer T> ? T : never };
 type Handler<P extends Pattern> = (session: Session, params: ParamsOf<P>) => void | Promise<void>;
 type SessionPredicate = (session: Session) => boolean;
+interface Command {
+  name: string;
+  pattern: Pattern;
+  handler: (session: Session, params: any) => void | Promise<void>;
+}
+interface RawPattern {
+  pattern: Pattern;
+  handler: (session: Session, params: any) => void | Promise<void>;
+}
+type RouteEntry =
+  | {
+      type: 'command';
+      command: Command;
+    }
+  | {
+      type: 'group';
+      name: string;
+      router: Router;
+    }
+  | {
+      type: 'filter';
+      predicate: SessionPredicate;
+      router: Router;
+    }
+  | {
+      type: 'rawPattern';
+      rawPattern: RawPattern;
+    };
+type RouteBranch =
+  | {
+      type: 'command';
+      path: string[];
+      command: Command;
+    }
+  | {
+      type: 'rawPattern';
+      path: string[];
+      rawPattern: RawPattern;
+    };
+type RouteMatchResult =
+  | {
+      type: 'command';
+      path: string[];
+      command: Command;
+      params: any;
+    }
+  | {
+      type: 'rawPattern';
+      path: string[];
+      rawPattern: RawPattern;
+      params: any;
+    };
 interface Session {
   raw: IncomingMessage;
   reply(segments: OutgoingSegment_ZodInput[]): Promise<void>;
@@ -5518,12 +5570,16 @@ declare class Router {
   rawPattern<P extends Pattern>(pattern: P, handler: Handler<P>): this;
   group(name: string): Router;
   filter(predicate: SessionPredicate): Router;
+  routes(): RouteEntry[];
+  branches(session: Session): RouteBranch[];
+  match(session: Session, message: IncomingMessage): RouteMatchResult | undefined;
   dispatch(session: Session, message: IncomingMessage): Promise<boolean>;
-  private process;
-  private processEntry;
-  private processCommand;
-  private processGroup;
-  private processRawPattern;
+  private matchFrom;
+  private matchEntry;
+  private matchCommand;
+  private matchGroup;
+  private matchRawPattern;
+  private branchesFrom;
   private capturePattern;
 }
 //#endregion
@@ -5567,13 +5623,31 @@ type ServiceClass<T extends object = object> = abstract new (...args: any[]) =>
 //#endregion
 //#region src/core/plugin.d.ts
 type ParameterList = Array<any>;
-interface Plugin<T extends ParameterList> {
+type Injection = Record<string, ServiceClass>;
+type InjectedServices<I extends Injection | undefined> = I extends Injection
+  ? { [K in keyof I]: InstanceType<I[K]> }
+  : {};
+type OptionalInjectedServices<I extends Injection | undefined> = I extends Injection
+  ? { [K in keyof I]: InstanceType<I[K]> | undefined }
+  : {};
+interface Plugin<
+  T extends ParameterList,
+  I extends Injection | undefined,
+  OI extends Injection | undefined = undefined,
+> {
   name: string;
   requires?: readonly ServiceClass[];
+  inject?: I;
+  optionalRequires?: readonly ServiceClass[];
+  optionalInject?: OI;
   provides?: readonly ServiceClass[];
-  apply(ctx: Context, ...args: T): void | Promise<void>;
+  apply(ctx: Context & InjectedServices<I> & OptionalInjectedServices<OI>, ...args: T): void | Promise<void>;
 }
-declare function definePlugin<T extends ParameterList>(plugin: Plugin<T>): Plugin<T>;
+declare function definePlugin<
+  T extends ParameterList,
+  I extends Injection | undefined,
+  OI extends Injection | undefined,
+>(plugin: Plugin<T, I, OI>): Plugin<T, I, OI>;
 //#endregion
 //#region src/core/context.d.ts
 interface ContextOptions {
@@ -5603,7 +5677,10 @@ declare class Context {
   private isStarted;
   private constructor();
   on<K extends keyof EventMap>(type: K, handler: (event: EventMap[K]) => void | Promise<void>): void;
-  install<T extends ParameterList>(plugin: Plugin<T>, ...args: T): void;
+  install<T extends ParameterList, I extends Injection | undefined, OI extends Injection | undefined>(
+    plugin: Plugin<T, I, OI>,
+    ...args: T
+  ): void;
   provide<T extends object>(service: ServiceClass<T>, instance: T): void;
   resolve<T extends object>(service: ServiceClass<T>): T;
   tryResolve<T extends object>(service: ServiceClass<T>): T | undefined;
@@ -5613,6 +5690,9 @@ declare class Context {
   private acceptsParentEvent;
   private applyPlugins;
   private sortPlugins;
+  private collectPendingProvidedServices;
+  private areRequiredServicesAvailable;
+  private areOptionalServicesReady;
   private collectAvailableServices;
   private createUnresolvablePluginError;
   private createProxyContextForPlugin;
@@ -5664,11 +5744,14 @@ declare namespace seg {
 //#endregion
 export {
   ApiEndpoints,
+  Command,
   Context,
   ContextOptions,
   ContextUrlOptions,
   EventMap,
   Filter,
+  Handler,
+  Injection,
   LogHandler,
   LogLevel,
   LogMessage,
@@ -5677,10 +5760,17 @@ export {
   MilkyEventSubscription,
   Parameter,
   ParameterList,
+  ParamsOf,
+  Pattern,
   Plugin,
+  RawPattern,
+  RouteBranch,
+  RouteEntry,
+  RouteMatchResult,
   Router,
   type ServiceClass,
   Session,
+  SessionPredicate,
   combineLogHandlers,
   createMilkyClient,
   definePlugin,

package/dist/index.mjs

@@ -211,49 +211,102 @@ var Router = class Router {
 		});
 		return router;
 	}
-	async dispatch(session, message) {
+	routes() {
+		return this.entries;
+	}
+	branches(session) {
+		return this.branchesFrom(session, []);
+	}
+	match(session, message) {
 		const tokenizer = new Tokenizer(message.segments);
-		return await this.process(session, tokenizer);
+		return this.matchFrom(session, tokenizer, []);
+	}
+	async dispatch(session, message) {
+		const match = this.match(session, message);
+		if (match === void 0) return false;
+		switch (match.type) {
+			case "command":
+				await match.command.handler(session, match.params);
+				break;
+			case "rawPattern":
+				await match.rawPattern.handler(session, match.params);
+				break;
+		}
+		return true;
 	}
-	async process(session, tokenizer) {
+	matchFrom(session, tokenizer, path) {
 		const initialState = tokenizer.getState();
 		for (const entry of this.entries) {
 			tokenizer.setState(initialState);
-			if (await this.processEntry(entry, session, tokenizer)) return true;
+			const match = this.matchEntry(entry, session, tokenizer, path);
+			if (match !== void 0) return match;
 		}
 		tokenizer.setState(initialState);
-		return false;
 	}
-	async processEntry(entry, session, tokenizer) {
+	matchEntry(entry, session, tokenizer, path) {
 		switch (entry.type) {
-			case "command": return await this.processCommand(entry.command, session, tokenizer);
-			case "group": return await this.processGroup(entry.name, entry.router, session, tokenizer);
+			case "command": return this.matchCommand(entry.command, tokenizer, path);
+			case "group": return this.matchGroup(entry.name, entry.router, session, tokenizer, path);
 			case "filter":
-				if (entry.predicate(session) !== true) return false;
-				return await entry.router.process(session, tokenizer);
-			case "rawPattern": return await this.processRawPattern(entry.rawPattern, session, tokenizer);
+				if (entry.predicate(session) !== true) return;
+				return entry.router.matchFrom(session, tokenizer, path);
+			case "rawPattern": return this.matchRawPattern(entry.rawPattern, tokenizer, path);
 		}
 	}
-	async processCommand(command, session, tokenizer) {
+	matchCommand(command, tokenizer, path) {
 		const token = tokenizer.peek();
-		if (typeof token !== "string" || token !== command.name) return false;
+		if (typeof token !== "string" || token !== command.name) return;
 		tokenizer.next();
 		const params = this.capturePattern(command.pattern, tokenizer);
-		if (params === void 0 || tokenizer.hasNext()) return false;
-		await command.handler(session, params);
-		return true;
+		if (params === void 0 || tokenizer.hasNext()) return;
+		return {
+			type: "command",
+			path: [...path],
+			command,
+			params
+		};
 	}
-	async processGroup(name, router, session, tokenizer) {
+	matchGroup(name, router, session, tokenizer, path) {
 		const token = tokenizer.peek();
-		if (typeof token !== "string" || token !== name) return false;
+		if (typeof token !== "string" || token !== name) return;
 		tokenizer.next();
-		return await router.process(session, tokenizer);
+		return router.matchFrom(session, tokenizer, [...path, name]);
 	}
-	async processRawPattern(rawPattern, session, tokenizer) {
+	matchRawPattern(rawPattern, tokenizer, path) {
 		const params = this.capturePattern(rawPattern.pattern, tokenizer);
-		if (params === void 0 || tokenizer.hasNext()) return false;
-		await rawPattern.handler(session, params);
-		return true;
+		if (params === void 0 || tokenizer.hasNext()) return;
+		return {
+			type: "rawPattern",
+			path: [...path],
+			rawPattern,
+			params
+		};
+	}
+	branchesFrom(session, path) {
+		const branches = [];
+		for (const entry of this.entries) switch (entry.type) {
+			case "command":
+				branches.push({
+					type: "command",
+					path: [...path],
+					command: entry.command
+				});
+				break;
+			case "group":
+				branches.push(...entry.router.branchesFrom(session, [...path, entry.name]));
+				break;
+			case "filter":
+				if (entry.predicate(session) === true) branches.push(...entry.router.branchesFrom(session, path));
+				break;
+			case "rawPattern":
+				branches.push({
+					type: "rawPattern",
+					path: [...path],
+					rawPattern: entry.rawPattern
+				});
+				break;
+		}
+		return branches;
 	}
 	capturePattern(pattern, tokenizer) {
 		const initialState = tokenizer.getState();
@@ -419,7 +472,10 @@ var Context = class Context {
 		const available = /* @__PURE__ */ new Set();
 		for (const service of this.collectAvailableServices()) available.add(service);
 		while (pending.length > 0) {
-			const nextIndex = pending.findIndex(({ plugin }) => (plugin.requires ?? []).every((service) => available.has(service)));
+			const availableByPendingPlugins = this.collectPendingProvidedServices(pending);
+			const requiredReadyIndex = pending.findIndex(({ plugin }) => this.areRequiredServicesAvailable(plugin, available));
+			const optionalReadyIndex = pending.findIndex(({ plugin }) => this.areRequiredServicesAvailable(plugin, available) && this.areOptionalServicesReady(plugin, available, availableByPendingPlugins));
+			const nextIndex = optionalReadyIndex === -1 ? requiredReadyIndex : optionalReadyIndex;
 			if (nextIndex === -1) throw this.createUnresolvablePluginError(pending, available);
 			const [next] = pending.splice(nextIndex, 1);
 			sorted.push(next);
@@ -427,6 +483,21 @@ var Context = class Context {
 		}
 		return sorted;
 	}
+	collectPendingProvidedServices(pending) {
+		const providedServices = /* @__PURE__ */ new Map();
+		for (const installedPlugin of pending) for (const service of installedPlugin.plugin.provides ?? []) providedServices.set(service, installedPlugin);
+		return providedServices;
+	}
+	areRequiredServicesAvailable(plugin, available) {
+		return (plugin.requires ?? []).every((service) => available.has(service));
+	}
+	areOptionalServicesReady(plugin, available, pendingProviders) {
+		return (plugin.optionalRequires ?? []).every((service) => {
+			if (available.has(service)) return true;
+			const pendingProvider = pendingProviders.get(service);
+			return pendingProvider === void 0 || pendingProvider.plugin === plugin;
+		});
+	}
 	collectAvailableServices() {
 		const services = [...this.services.keys()];
 		if (this.parent) services.push(...this.parent.collectAvailableServices());
@@ -450,8 +521,18 @@ var Context = class Context {
 	}
 	createProxyContextForPlugin(plugin) {
 		const proxyLogger = new Logger((message) => this.logHandler?.(message), plugin.name);
+		let proxyInjections;
+		if (plugin.inject) {
+			proxyInjections = {};
+			for (const [key, service] of Object.entries(plugin.inject)) proxyInjections[key] = this.resolve(service);
+		}
+		if (plugin.optionalInject) {
+			proxyInjections ??= {};
+			for (const [key, service] of Object.entries(plugin.optionalInject)) proxyInjections[key] = this.tryResolve(service);
+		}
 		return new Proxy(this, { get(target, prop) {
 			if (prop === "logger") return proxyLogger;
+			else if (proxyInjections && prop in proxyInjections) return proxyInjections[prop];
 			else return target[prop];
 		} });
 	}
@@ -615,6 +696,14 @@ let filter;
 //#endregion
 //#region src/core/plugin.ts
 function definePlugin(plugin) {
+	if (plugin.inject) {
+		if (plugin.requires) throw new Error(`Plugin "${plugin.name}" cannot have both "requires" and "inject" properties.`);
+		plugin.requires = Object.values(plugin.inject);
+	}
+	if (plugin.optionalInject) {
+		if (plugin.optionalRequires) throw new Error(`Plugin "${plugin.name}" cannot have both "optionalRequires" and "optionalInject" properties.`);
+		plugin.optionalRequires = Object.values(plugin.optionalInject);
+	}
 	return plugin;
 }
 //#endregion

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fraqjs/fraq",
   "type": "module",
-  "version": "0.3.3",
+  "version": "0.5.0",
   "description": "Milky Bot framework",
   "files": [
     "dist"
@@ -19,6 +19,9 @@
   "dependencies": {
     "mitt": "^3.0.1"
   },
+  "devDependencies": {
+    "@fraqjs/mock": "^0.1.0"
+  },
   "engines": {
     "node": ">=22"
   },