Merge pull request #88 from bootgs/max/next

MaksymStoianov · web-flow · commit 344fb4e32c1d · 2026-03-20T13:14:15.000+01:00
Max/next
diff --git a/src/controller/BootApplication.ts b/src/controller/BootApplication.ts
@@ -1,14 +1,11 @@
 import { ApplicationConfig, InjectionToken, Newable } from "../domain/types";
 import { AppsScriptEventType, RequestMethod } from "../domain/enums";
-import {
-  EventDispatcher,
-  RequestFactory,
-  Resolver,
-  ResponseBuilder,
-  Router,
-  RouterExplorer
-} from "../service";
+import { EventDispatcher, RequestFactory, Resolver, ResponseBuilder, Router, RouterExplorer } from "../service";
+import { isSymbol } from "apps-script-utils";
 
+/**
+ * Main application class for bootstrapping and handling Google Apps Script events.
+ */
 export class BootApplication {
   private readonly _controllers = new Map<Newable, unknown>();
   private readonly _providers = new Map<InjectionToken, unknown>();
@@ -18,6 +15,11 @@ export class BootApplication {
   private readonly _responseBuilder = new ResponseBuilder();
   private readonly _eventDispatcher: EventDispatcher;
 
+  /**
+   * Creates a new instance of BootApplication.
+   *
+   * @param {ApplicationConfig} config The application configuration.
+   */
   constructor(config: ApplicationConfig) {
     (config.controllers || []).forEach((c) => this._controllers.set(c, null));
 
@@ -50,26 +52,62 @@ export class BootApplication {
     this._eventDispatcher = new EventDispatcher(this._resolver, this._controllers);
   }
 
+  /**
+   * Handles Google Apps Script doGet events.
+   *
+   * @param {GoogleAppsScript.Events.DoGet} event The doGet event object.
+   * @returns {Promise<GoogleAppsScript.HTML.HtmlOutput | GoogleAppsScript.Content.TextOutput>} The response object.
+   */
   public async doGet(event: GoogleAppsScript.Events.DoGet) {
     return this.handleHttpRequest(RequestMethod.GET, event);
   }
 
+  /**
+   * Handles Google Apps Script doPost events.
+   *
+   * @param {GoogleAppsScript.Events.DoPost} event The doPost event object.
+   * @returns {Promise<GoogleAppsScript.HTML.HtmlOutput | GoogleAppsScript.Content.TextOutput>} The response object.
+   */
   public async doPost(event: GoogleAppsScript.Events.DoPost) {
     return this.handleHttpRequest(RequestMethod.POST, event);
   }
 
+  /**
+   * Handles Google Apps Script onInstall events.
+   *
+   * @param {GoogleAppsScript.Events.AddonOnInstall} event The onInstall event object.
+   * @returns {Promise<void>}
+   */
   public async onInstall(event: GoogleAppsScript.Events.AddonOnInstall) {
     await this._eventDispatcher.dispatch(AppsScriptEventType.INSTALL, event);
   }
 
+  /**
+   * Handles Google Apps Script onOpen events.
+   *
+   * @param {GoogleAppsScript.Events.AppsScriptEvent} event The onOpen event object.
+   * @returns {Promise<void>}
+   */
   public async onOpen(event: GoogleAppsScript.Events.AppsScriptEvent) {
     await this._eventDispatcher.dispatch(AppsScriptEventType.OPEN, event);
   }
 
+  /**
+   * Handles Google Apps Script onEdit events.
+   *
+   * @param {GoogleAppsScript.Events.SheetsOnEdit} event The onEdit event object.
+   * @returns {Promise<void>}
+   */
   public async onEdit(event: GoogleAppsScript.Events.SheetsOnEdit) {
     await this._eventDispatcher.dispatch(AppsScriptEventType.EDIT, event);
   }
 
+  /**
+   * Handles Google Apps Script onChange events.
+   *
+   * @param {GoogleAppsScript.Events.SheetsOnChange} event The onChange event object.
+   * @returns {Promise<void>}
+   */
   public async onChange(event: GoogleAppsScript.Events.SheetsOnChange) {
     await this._eventDispatcher.dispatch(AppsScriptEventType.CHANGE, event);
   }
@@ -79,10 +117,42 @@ export class BootApplication {
   //   await this.eventDispatcher.dispatch(AppsScriptEventType.SELECTION_CHANGE, event);
   // }
 
+  /**
+   * Handles Google Apps Script onFormSubmit events.
+   *
+   * @param {GoogleAppsScript.Events.FormsOnFormSubmit} event The onFormSubmit event object.
+   * @returns {Promise<void>}
+   */
   public async onFormSubmit(event: GoogleAppsScript.Events.FormsOnFormSubmit) {
     await this._eventDispatcher.dispatch(AppsScriptEventType.FORM_SUBMIT, event);
   }
 
+  /**
+   * Returns a Proxy object that can be used to handle Google Apps Script menu actions.
+   *
+   * @returns {any} A Proxy object.
+   */
+  public onMenu(): any {
+    return new Proxy(this, {
+      get(target, prop, receiver) {
+        if (prop === "inspect" || isSymbol(prop)) {
+          return Reflect.get(target, prop, receiver);
+        }
+
+        return (event: GoogleAppsScript.Events.AppsScriptEvent) => {
+          return target._eventDispatcher.dispatchByName(prop as string, event);
+        };
+      }
+    });
+  }
+
+  /**
+   * Handles incoming HTTP requests and routes them to the appropriate controller.
+   *
+   * @param {RequestMethod} method The HTTP method (GET or POST).
+   * @param {GoogleAppsScript.Events.DoGet | GoogleAppsScript.Events.DoPost} event The Apps Script event object.
+   * @returns {Promise<GoogleAppsScript.HTML.HtmlOutput | GoogleAppsScript.Content.TextOutput>} The response object.
+   */
   private async handleHttpRequest(
     method: RequestMethod,
     event: GoogleAppsScript.Events.DoGet | GoogleAppsScript.Events.DoPost
diff --git a/src/controller/BootApplicationFactory.ts b/src/controller/BootApplicationFactory.ts
@@ -1,6 +1,9 @@
 import { ApplicationConfig } from "../domain/types";
 import { BootApplication } from "../controller";
 
+/**
+ * Factory for creating BootApplication instances.
+ */
 export class BootApplicationFactory {
   /**
    * Creates an instance of BootApplication.
diff --git a/src/controller/decorators/appsscript/OnChange.ts b/src/controller/decorators/appsscript/OnChange.ts
@@ -1,4 +1,7 @@
 import { AppsScriptEventType } from "../../../domain/enums";
 import { createAppsScriptDecorator } from "../../../repository";
 
+/**
+ * Decorator for handling Google Apps Script onChange events.
+ */
 export const OnChange = createAppsScriptDecorator(AppsScriptEventType.CHANGE);
diff --git a/src/controller/decorators/appsscript/OnEdit.ts b/src/controller/decorators/appsscript/OnEdit.ts
@@ -1,4 +1,7 @@
 import { AppsScriptEventType } from "../../../domain/enums";
 import { createAppsScriptDecorator } from "../../../repository";
 
+/**
+ * Decorator for handling Google Apps Script onEdit events.
+ */
 export const OnEdit = createAppsScriptDecorator(AppsScriptEventType.EDIT);
diff --git a/src/controller/decorators/appsscript/OnFormSubmit.ts b/src/controller/decorators/appsscript/OnFormSubmit.ts
@@ -1,4 +1,7 @@
 import { AppsScriptEventType } from "../../../domain/enums";
 import { createAppsScriptDecorator } from "../../../repository";
 
+/**
+ * Decorator for handling Google Apps Script onFormSubmit events.
+ */
 export const OnFormSubmit = createAppsScriptDecorator(AppsScriptEventType.FORM_SUBMIT);
diff --git a/src/controller/decorators/appsscript/OnInstall.ts b/src/controller/decorators/appsscript/OnInstall.ts
@@ -1,4 +1,7 @@
 import { AppsScriptEventType } from "../../../domain/enums";
 import { createAppsScriptDecorator } from "../../../repository";
 
+/**
+ * Decorator for handling Google Apps Script onInstall events.
+ */
 export const OnInstall = createAppsScriptDecorator(AppsScriptEventType.INSTALL);
diff --git a/src/controller/decorators/appsscript/OnOpen.ts b/src/controller/decorators/appsscript/OnOpen.ts
@@ -1,4 +1,7 @@
 import { AppsScriptEventType } from "../../../domain/enums";
 import { createAppsScriptDecorator } from "../../../repository";
 
+/**
+ * Decorator for handling Google Apps Script onOpen events.
+ */
 export const OnOpen = createAppsScriptDecorator(AppsScriptEventType.OPEN);
diff --git a/src/service/EventDispatcher.ts b/src/service/EventDispatcher.ts
@@ -8,13 +8,30 @@ import { AppsScriptEventType, ParamSource } from "../domain/enums";
 import { InjectTokenDefinition, Newable, ParamDefinition } from "../domain/types";
 import { getInjectionTokens } from "../repository";
 import { Resolver } from "../service";
+import { isFunctionLike } from "apps-script-utils";
 
+/**
+ * Service for dispatching events to controllers.
+ */
 export class EventDispatcher {
+  /**
+   * Creates a new instance of EventDispatcher.
+   *
+   * @param {Resolver} resolver The dependency resolver.
+   * @param {Map<Newable, unknown>} controllers The registered controllers.
+   */
   constructor(
     private readonly resolver: Resolver,
     private readonly controllers: Map<Newable, unknown>
   ) {}
 
+  /**
+   * Dispatches an event to the registered controllers.
+   *
+   * @param {AppsScriptEventType} eventType The type of the event to dispatch.
+   * @param {unknown} event The event object.
+   * @returns {Promise<void>} A promise that resolves when all handlers have finished.
+   */
   public async dispatch(eventType: AppsScriptEventType, event: unknown): Promise<void> {
     for (const controller of this.controllers.keys()) {
       const prototype = controller.prototype;
@@ -44,6 +61,66 @@ export class EventDispatcher {
     }
   }
 
+  /**
+   * Dispatches an event to the registered controllers by its name.
+   *
+   * @param {string} methodName The name of the method to dispatch the event to.
+   * @param {unknown} event The event object.
+   * @returns {Promise<void>} A promise that resolves when all handlers have finished.
+   */
+  public async dispatchByName(methodName: string, event: unknown): Promise<void> {
+    for (const controller of this.controllers.keys()) {
+      const instance = this.resolver.resolve(controller) as Record<string, any>;
+
+      const prototype = Object.getPrototypeOf(instance);
+
+      const methodNames: string[] = [];
+
+      let currentProto = prototype;
+
+      while (currentProto && currentProto !== Object.prototype) {
+        Object.getOwnPropertyNames(currentProto).forEach((name) => {
+          if (name !== "constructor" && isFunctionLike(currentProto[ name ])) {
+            methodNames.push(name);
+          }
+        });
+        currentProto = Object.getPrototypeOf(currentProto);
+      }
+
+      if (!methodNames.includes(methodName)) {
+        continue;
+      }
+
+      const handler = instance[ methodName ].bind(instance);
+
+      if (!isFunctionLike(handler)) {
+        console.warn(
+          "Method '%s' in controller '%s' is not a callable function and was skipped during event handling.",
+          methodName,
+          controller.name
+        );
+
+        continue;
+      }
+
+      const args = this.buildMethodParams(instance as object, methodName, event);
+
+      try {
+        await handler(...args);
+      } catch (err: unknown) {
+        console.error("Error:", err instanceof Error ? err.stack : String(err));
+      }
+    }
+  }
+
+  /**
+   * Builds the parameters for a controller method.
+   *
+   * @param {object} target The target object.
+   * @param {string | symbol} propertyKey The name of the property.
+   * @param {unknown} event The event object.
+   * @returns {unknown[]} An array of parameters for the method.
+   */
   public buildMethodParams(
     target: object,
     propertyKey: string | symbol,
@@ -98,6 +175,14 @@ export class EventDispatcher {
     return args;
   }
 
+  /**
+   * Checks if the event should be dispatched based on the provided options.
+   *
+   * @param {AppsScriptEventType} eventType The type of the event.
+   * @param {unknown} event The event object.
+   * @param {Record<string, unknown> | undefined} options The options to check against.
+   * @returns {boolean} True if the event should be dispatched, false otherwise.
+   */
   private checkFilters(
     eventType: AppsScriptEventType,
     event: unknown,
diff --git a/src/service/RequestFactory.ts b/src/service/RequestFactory.ts
@@ -2,6 +2,9 @@ import { isString, normalize } from "apps-script-utils";
 import { HttpHeaders, HttpRequest, ParsedUrl } from "../domain/types";
 import { RequestMethod } from "../domain/enums";
 
+/**
+ * Factory for creating structured HttpRequest objects.
+ */
 export class RequestFactory {
   /**
    * Creates a structured HttpRequest object from a raw Apps Script DoGet or DoPost event.
diff --git a/src/service/Resolver.ts b/src/service/Resolver.ts
@@ -5,12 +5,28 @@ import { PARAMTYPES_METADATA } from "../domain/constants";
 import { getInjectionTokens } from "../repository";
 import { isController, isInjectable } from "../shared/utils";
 
+/**
+ * Dependency injection resolver.
+ */
 export class Resolver {
+  /**
+   * Creates a new instance of Resolver.
+   *
+   * @param {Map<InjectionToken, unknown>} _controllers Registered controllers.
+   * @param {Map<InjectionToken, unknown>} _providers Registered providers.
+   */
   constructor(
     private readonly _controllers: Map<InjectionToken, unknown>,
     private readonly _providers: Map<InjectionToken, unknown>
   ) {}
 
+  /**
+   * Resolves a dependency by its injection token.
+   *
+   * @param {InjectionToken<T>} token The injection token.
+   * @returns {T} The resolved instance.
+   * @throws {Error} If the dependency cannot be resolved.
+   */
   public resolve<T>(token: InjectionToken<T>): T {
     if (this._controllers.has(token)) {
       const instance = this._controllers.get(token);
diff --git a/src/service/ResponseBuilder.ts b/src/service/ResponseBuilder.ts
@@ -1,6 +1,9 @@
 import { HeaderAcceptMimeType, HttpStatus, RequestMethod } from "../domain/enums";
 import { HttpHeaders, HttpRequest, HttpResponse } from "../domain/types";
 
+/**
+ * Service for building and wrapping HTTP responses.
+ */
 export class ResponseBuilder {
   /**
    * Creates a structured HttpResponse object.
diff --git a/src/service/Router.ts b/src/service/Router.ts
@@ -14,14 +14,31 @@ import { RouteExecutionContext } from "../domain/entities";
 import { getInjectionTokens } from "../repository";
 import { PathMatcher, Resolver } from "../service";
 
+/**
+ * Router service for handling HTTP requests and dispatching them to controllers.
+ */
 export class Router {
   private readonly pathMatcher = new PathMatcher();
 
+  /**
+   * Creates a new instance of Router.
+   *
+   * @param {Resolver} _resolver The dependency resolver.
+   * @param {RouteMetadata[]} _routes The registered routes.
+   */
   constructor(
     private readonly _resolver: Resolver,
     private readonly _routes: RouteMetadata[]
   ) {}
 
+  /**
+   * Handles an incoming HTTP request.
+   *
+   * @param {HttpRequest} request The HTTP request object.
+   * @param {GoogleAppsScript.Events.DoGet | GoogleAppsScript.Events.DoPost} event The Apps Script event object.
+   * @param {Function} responseBuilder A function to build an HTTP response.
+   * @returns {Promise<HttpResponse>} A promise that resolves to the HTTP response.
+   */
   public async handle(
     request: HttpRequest,
     event: GoogleAppsScript.Events.DoGet | GoogleAppsScript.Events.DoPost,
@@ -79,6 +96,14 @@ export class Router {
     }
   }
 
+  /**
+   * Builds the parameters for a controller method based on the route execution context.
+   *
+   * @param {object} target The target object.
+   * @param {string | symbol} propertyKey The name of the property.
+   * @param {RouteExecutionContext} ctx The route execution context.
+   * @returns {unknown[]} An array of parameters for the method.
+   */
   private buildMethodParams(
     target: object,
     propertyKey: string | symbol,
diff --git a/src/service/RouterExplorer.ts b/src/service/RouterExplorer.ts
diff --git a/src/shared/utils/isController.ts b/src/shared/utils/isController.ts
diff --git a/src/shared/utils/isInjectable.ts b/src/shared/utils/isInjectable.ts
diff --git a/test/unit/controller/BootApplication/BootApplication.menu.unit.test.ts b/test/unit/controller/BootApplication/BootApplication.menu.unit.test.ts
