@haskou/ddd-kernel 0.1.1 → 1.0.0

package/dist/adapters/ui/index.cjs

@@ -31,34 +31,101 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var ui_exports = {};
 __export(ui_exports, {
   ExpressKernelServer: () => ExpressKernelServer,
+  HttpErrorHandler: () => HttpErrorHandler,
   Route: () => Route,
   RoutePrefix: () => RoutePrefix
 });
 module.exports = __toCommonJS(ui_exports);
 
 // src/adapters/ui/express/ExpressKernelServer.ts
-var import_routing_controllers = require("routing-controllers");
+var import_node_module = require("module");
+var import_node_path = __toESM(require("path"), 1);
 var ExpressKernelServer = class {
   constructor(options) {
     this.options = options;
+    this.afterControllersHooks = this.copy(options.afterControllersHooks);
+    this.beforeControllersHooks = this.copy(options.beforeControllersHooks);
+    this.controllers = this.copy(options.controllers);
+    this.errorHandlers = this.copy(options.errorHandlers);
+    this.hooks = this.copy(options.hooks);
+    this.middlewares = this.copy(options.middlewares);
+    this.postControllerMiddlewares = this.copy(
+      options.postControllerMiddlewares
+    );
+    this.preControllerMiddlewares = this.copy(options.preControllerMiddlewares);
+    this.staticHooks = this.copy(options.staticHooks);
+    this.swaggerHooks = this.copy(options.swaggerHooks);
   }
   options;
+  applicationRequire = (0, import_node_module.createRequire)(
+    import_node_path.default.resolve(process.cwd(), "package.json")
+  );
+  afterControllersHooks;
   appInstance;
+  beforeControllersHooks;
+  controllers;
+  errorHandlers;
+  hooks;
+  middlewares;
+  postControllerMiddlewares;
+  preControllerMiddlewares;
   serverInstance;
-  registerErrorHandlers(app) {
-    const handlers = this.options.errorHandlers ?? [this.defaultErrorHandler()];
+  staticHooks;
+  swaggerHooks;
+  copy(items) {
+    return [...items ?? []];
+  }
+  configureControllerContainer() {
+    const { useContainer } = this.getRoutingControllers();
+    useContainer(
+      {
+        /* c8 ignore next */
+        get: (ClassDefinition) => this.options.kernel.di.getService(ClassDefinition)
+      },
+      {
+        fallback: true,
+        fallbackOnErrors: true
+      }
+    );
+  }
+  getExpress() {
+    return this.applicationRequire("express");
+  }
+  getRoutingControllers() {
+    return this.applicationRequire("routing-controllers");
+  }
+  applyErrorHandlers(app) {
+    const handlers = this.errorHandlers.length > 0 ? this.errorHandlers : [this.defaultErrorHandler()];
     for (const handler of handlers) {
       app.use(handler);
     }
   }
   defaultErrorHandler() {
-    return (error, request, response) => {
+    return (error, request, response, next) => {
+      void next;
       void request;
       response.status(500).json({
         error: error instanceof Error ? error.message : String(error)
       });
     };
   }
+  async runHooks(hooks, app) {
+    for (const hook of hooks) {
+      await hook(app);
+    }
+  }
+  async runPhaseHooks(phase, app) {
+    for (const hook of this.hooks) {
+      if (hook.phase === phase) {
+        await hook.handle(app);
+      }
+    }
+  }
+  applyMiddlewares(app, middlewares) {
+    for (const middleware of middlewares) {
+      app.use(middleware);
+    }
+  }
   get app() {
     if (!this.appInstance) {
       throw new Error("HTTP server is not running.");
@@ -71,6 +138,11 @@ var ExpressKernelServer = class {
     }
     return this.serverInstance;
   }
+  assertServerIsNotRunning() {
+    if (this.serverInstance) {
+      throw new Error("HTTP server is already running.");
+    }
+  }
   close() {
     if (!this.serverInstance) {
       return Promise.resolve();
@@ -87,15 +159,74 @@ var ExpressKernelServer = class {
       });
     });
   }
-  run() {
-    const app = (0, import_routing_controllers.createExpressServer)({
-      controllers: this.options.kernel.getRoutes(),
+  registerAfterControllersHooks(...hooks) {
+    this.assertServerIsNotRunning();
+    this.afterControllersHooks?.push(...hooks);
+    return this;
+  }
+  registerBeforeControllersHooks(...hooks) {
+    this.assertServerIsNotRunning();
+    this.beforeControllersHooks?.push(...hooks);
+    return this;
+  }
+  registerControllers(...controllers) {
+    this.assertServerIsNotRunning();
+    this.controllers.push(...controllers);
+    return this;
+  }
+  registerErrorHandlers(...handlers) {
+    this.assertServerIsNotRunning();
+    this.errorHandlers.push(...handlers);
+    return this;
+  }
+  registerHooks(...hooks) {
+    this.assertServerIsNotRunning();
+    this.hooks.push(...hooks);
+    return this;
+  }
+  registerMiddlewares(...middlewares) {
+    this.assertServerIsNotRunning();
+    this.middlewares.push(...middlewares);
+    return this;
+  }
+  registerPostControllerMiddlewares(...middlewares) {
+    this.assertServerIsNotRunning();
+    this.postControllerMiddlewares.push(...middlewares);
+    return this;
+  }
+  registerPreControllerMiddlewares(...middlewares) {
+    this.assertServerIsNotRunning();
+    this.preControllerMiddlewares.push(...middlewares);
+    return this;
+  }
+  async run() {
+    if (this.serverInstance) {
+      throw new Error("HTTP server is already running.");
+    }
+    const controllers = [
+      ...this.options.kernel.getRoutes(),
+      ...this.controllers
+    ];
+    const express = this.getExpress();
+    const { useExpressServer } = this.getRoutingControllers();
+    const app = express();
+    this.applyMiddlewares(app, this.middlewares);
+    this.applyMiddlewares(app, this.preControllerMiddlewares);
+    await this.runHooks(this.beforeControllersHooks, app);
+    await this.runPhaseHooks("beforeControllers", app);
+    this.configureControllerContainer();
+    useExpressServer(app, {
+      ...this.options.routingControllersOptions,
+      controllers,
       routePrefix: this.options.routePrefix
     });
-    for (const middleware of this.options.middlewares ?? []) {
-      app.use(middleware);
-    }
-    this.registerErrorHandlers(app);
+    this.applyMiddlewares(app, this.postControllerMiddlewares);
+    await this.runHooks(this.afterControllersHooks, app);
+    await this.runPhaseHooks("afterControllers", app);
+    await this.runHooks(this.swaggerHooks, app);
+    await this.runHooks(this.staticHooks, app);
+    await this.runPhaseHooks("beforeErrors", app);
+    this.applyErrorHandlers(app);
     this.appInstance = app;
     return new Promise((resolve) => {
       this.serverInstance = app.listen(this.options.port ?? 3e3, () => {
@@ -105,6 +236,132 @@ var ExpressKernelServer = class {
   }
 };
 
+// src/adapters/ui/express/HttpErrorHandler.ts
+var import_routing_controllers = require("routing-controllers");
+
+// src/contracts/ui/HttpRouteStatusEnum.ts
+var HttpRouteStatusEnum = {
+  BAD_REQUEST: 400,
+  CONFLICT: 409,
+  CREATED: 201,
+  DEPRECATED: 299,
+  FORBIDDEN: 403,
+  INTERNAL_SERVER_ERROR: 500,
+  NO_CONTENT: 204,
+  NOT_FOUND: 404,
+  OK: 200,
+  PAYLOAD_TOO_LARGE: 413,
+  SERVICE_UNAVAILABLE: 503,
+  TOO_MANY_REQUESTS: 429,
+  UNAUTHORIZED: 401,
+  UNPROCESSABLE_ENTITY: 422
+};
+
+// src/adapters/ui/express/HttpErrorHandler.ts
+var HttpErrorHandler = class {
+  constructor(options = {}) {
+    this.options = options;
+    this.handlers = options.handlers ?? [];
+    this.exposeUnhandledErrorsIn = options.exposeUnhandledErrorsIn ?? [
+      "local",
+      "test"
+    ];
+  }
+  options;
+  handlers;
+  exposeUnhandledErrorsIn;
+  formatValidationErrors(errors) {
+    return errors.flatMap((error) => {
+      if (error.children && error.children.length > 0) {
+        return this.formatValidationErrors(error.children);
+      }
+      return [
+        {
+          details: error.constraints,
+          property: error.property,
+          value: error.value
+        }
+      ];
+    });
+  }
+  getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+  getHttpStatus(error) {
+    return error.httpCode ?? error.statusCode ?? error.status;
+  }
+  isPayloadTooLargeError(error) {
+    return error.type === "entity.too.large" || this.getHttpStatus(error) === HttpRouteStatusEnum.PAYLOAD_TOO_LARGE;
+  }
+  logUnhandledError(error) {
+    this.options.logger?.error(`Unhandled error: ${error.message}`);
+    this.options.logger?.debug(error.stack ?? "No stack trace available");
+  }
+  handleSyntaxError(error, response) {
+    if (!(error instanceof SyntaxError)) {
+      return false;
+    }
+    response.status(HttpRouteStatusEnum.BAD_REQUEST).json({
+      code: "SyntaxError",
+      message: "Malformed JSON"
+    });
+    return true;
+  }
+  handlePayloadTooLargeError(error, response) {
+    if (!this.isPayloadTooLargeError(error)) {
+      return false;
+    }
+    response.status(HttpRouteStatusEnum.PAYLOAD_TOO_LARGE).json({
+      code: "PayloadTooLargeError",
+      httpStatus: HttpRouteStatusEnum.PAYLOAD_TOO_LARGE,
+      message: "Request entity too large."
+    });
+    return true;
+  }
+  handleHttpError(error, response) {
+    const httpError = error;
+    const httpStatus = this.getHttpStatus(httpError);
+    if (!httpStatus && !(error instanceof import_routing_controllers.HttpError)) {
+      return false;
+    }
+    response.status(httpStatus ?? HttpRouteStatusEnum.INTERNAL_SERVER_ERROR).json({
+      code: error.name,
+      errors: this.formatValidationErrors(
+        error.errors ?? []
+      ),
+      httpStatus: httpStatus ?? HttpRouteStatusEnum.INTERNAL_SERVER_ERROR,
+      message: error.message
+    });
+    return true;
+  }
+  handleUnhandledError(error, response) {
+    if (this.exposeUnhandledErrorsIn.includes(process.env.NODE_ENV ?? "")) {
+      this.logUnhandledError(error);
+    }
+    response.status(HttpRouteStatusEnum.INTERNAL_SERVER_ERROR).json({
+      code: error.constructor.name || String(HttpRouteStatusEnum.INTERNAL_SERVER_ERROR),
+      message: error.message || "Unknown error"
+    });
+  }
+  error(error, request, response, next) {
+    void request;
+    const handlers = [
+      this.handleSyntaxError.bind(this),
+      this.handlePayloadTooLargeError.bind(this),
+      ...this.handlers,
+      this.handleHttpError.bind(this)
+    ];
+    if (handlers.some((handler) => handler(error, response))) {
+      return;
+    }
+    void next;
+    this.handleUnhandledError(error, response);
+  }
+  handle = (error, request, response, next) => {
+    this.error(error, request, response, next);
+  };
+};
+
 // src/adapters/ui/express/RoutePrefix.ts
 var RoutePrefix = class _RoutePrefix {
   value;
@@ -131,7 +388,7 @@ var RoutePrefix = class _RoutePrefix {
 };
 
 // src/Kernel.ts
-var import_node_path2 = __toESM(require("path"), 1);
+var import_node_path3 = __toESM(require("path"), 1);
 
 // src/adapters/kernel/console/ConsoleKernelLogger.ts
 var ConsoleKernelLogger = class {
@@ -152,17 +409,17 @@ var ConsoleKernelLogger = class {
 // src/infrastructure/dependency-injection/DependencyInjection.ts
 var import_fs_extra = __toESM(require("fs-extra"), 1);
 var import_node_dependency_injection = require("node-dependency-injection");
-var import_node_path = __toESM(require("path"), 1);
+var import_node_path2 = __toESM(require("path"), 1);
 var DependencyInjection = class _DependencyInjection {
   constructor(options = {
     containerBuild: process.env.CONTAINER_BUILD === "true",
-    servicesYamlPath: import_node_path.default.resolve(
+    servicesYamlPath: import_node_path2.default.resolve(
       process.cwd(),
       "config",
       "container",
       "services.yaml"
     ),
-    sourceDirectory: import_node_path.default.resolve(process.cwd(), "src")
+    sourceDirectory: import_node_path2.default.resolve(process.cwd(), "src")
   }) {
     this.options = options;
     this.container = new import_node_dependency_injection.ContainerBuilder(false, this.options.sourceDirectory);
@@ -172,6 +429,7 @@ var DependencyInjection = class _DependencyInjection {
   autowire;
   loader;
   container;
+  overrideTokenIds = /* @__PURE__ */ new Map();
   static configure(options) {
     _DependencyInjection.configuredInstance = new _DependencyInjection(options);
     return _DependencyInjection.configuredInstance;
@@ -191,11 +449,21 @@ var DependencyInjection = class _DependencyInjection {
     return container._alias || /* @__PURE__ */ new Map();
   }
   async ensureFolderExists(filePath) {
-    await import_fs_extra.default.mkdir(import_node_path.default.dirname(filePath), { recursive: true });
+    await import_fs_extra.default.mkdir(import_node_path2.default.dirname(filePath), { recursive: true });
   }
   getServiceClassName(serviceName) {
     return typeof serviceName === "function" ? serviceName.name : void 0;
   }
+  getOverrideId(prefix, token) {
+    const tokenName = this.getServiceClassName(token) ?? String(token);
+    return `ddd-kernel.override.${prefix}.${tokenName}`;
+  }
+  ensureSyntheticService(id, value) {
+    const definition = this.container.register(id);
+    definition.public = true;
+    definition.synthetic = true;
+    this.container.set(id, value);
+  }
   parentMatchesService(parentId, serviceClassName) {
     if (!parentId) {
       return false;
@@ -207,6 +475,26 @@ var DependencyInjection = class _DependencyInjection {
     const serviceName = Buffer.from(serviceId, "base64").toString("utf8");
     return serviceName.endsWith(`__${serviceClassName}__${serviceClassName}`);
   }
+  serviceIdReferencesService(serviceId, serviceClassName) {
+    const serviceName = Buffer.from(serviceId, "base64").toString("utf8");
+    return serviceName.endsWith(`__${serviceClassName}`);
+  }
+  getReferenceId(value) {
+    if (typeof value === "object" && value !== null && "id" in value && typeof value.id === "string") {
+      return value.id;
+    }
+    return void 0;
+  }
+  getDefinitionArgumentReferences(definition) {
+    return [
+      ...definition._args ?? [],
+      ...definition._appendArgs ?? [],
+      ...definition._overrideArgs ?? []
+    ].flatMap((argument) => {
+      const referenceId = this.getReferenceId(argument);
+      return referenceId ? [referenceId] : [];
+    });
+  }
   findConcreteChildServiceId(serviceName) {
     const serviceClassName = this.getServiceClassName(serviceName);
     if (!serviceClassName) {
@@ -237,6 +525,86 @@ var DependencyInjection = class _DependencyInjection {
     );
     return matches[matches.length - 1];
   }
+  findReferencedServiceIds(serviceName) {
+    const serviceClassName = this.getServiceClassName(serviceName);
+    if (!serviceClassName) {
+      return [];
+    }
+    return [
+      ...new Set(
+        [...this.definitions.values()].flatMap(
+          (definition) => this.getDefinitionArgumentReferences(definition)
+        ).filter(
+          (id) => this.serviceIdReferencesService(id, serviceClassName)
+        )
+      )
+    ];
+  }
+  getOverrideTokenIds(token) {
+    const tokenIds = [
+      this.findRegisteredServiceId(token),
+      this.findAliasServiceId(token),
+      ...this.findReferencedServiceIds(token)
+    ].filter((id) => id !== void 0);
+    const existingTokenIds = [...new Set(tokenIds)];
+    if (existingTokenIds.length > 0) {
+      return existingTokenIds;
+    }
+    const overrideTokenId = this.getOverrideId("token", token);
+    this.ensureSyntheticService(overrideTokenId, void 0);
+    return [overrideTokenId];
+  }
+  getOverrideClassServiceId(ClassDefinition) {
+    const registeredServiceId = this.findRegisteredServiceId(ClassDefinition);
+    if (registeredServiceId) {
+      return registeredServiceId;
+    }
+    const overrideClassId = this.getOverrideId("class", ClassDefinition);
+    this.container.register(overrideClassId, ClassDefinition);
+    return overrideClassId;
+  }
+  applyClassOverride(override) {
+    if (!("useClass" in override)) {
+      return;
+    }
+    const tokenIds = this.getOverrideTokenIds(override.token);
+    const classId = this.getOverrideClassServiceId(override.useClass);
+    this.overrideTokenIds.set(override.token, tokenIds[0]);
+    for (const tokenId of tokenIds) {
+      this.container.setAlias(tokenId, classId);
+    }
+  }
+  applyFactoryOverride(override) {
+    if (!("useFactory" in override)) {
+      return;
+    }
+    const tokenIds = this.getOverrideTokenIds(override.token);
+    const factoryId = this.getOverrideId("factory", override.token);
+    this.ensureSyntheticService(factoryId, override.useFactory(this));
+    this.overrideTokenIds.set(override.token, tokenIds[0]);
+    for (const tokenId of tokenIds) {
+      this.container.setAlias(tokenId, factoryId);
+    }
+  }
+  applyValueOverride(override) {
+    if (!("useValue" in override)) {
+      return;
+    }
+    const tokenIds = this.getOverrideTokenIds(override.token);
+    const valueId = this.getOverrideId("value", override.token);
+    this.ensureSyntheticService(valueId, override.useValue);
+    this.overrideTokenIds.set(override.token, tokenIds[0]);
+    for (const tokenId of tokenIds) {
+      this.container.setAlias(tokenId, valueId);
+    }
+  }
+  applyOverrides() {
+    for (const override of this.options.overrides ?? []) {
+      this.applyClassOverride(override);
+      this.applyFactoryOverride(override);
+      this.applyValueOverride(override);
+    }
+  }
   registerParentAliases() {
     for (const [id, definition] of this.definitions.entries()) {
       if (definition._abstract === true || !definition._parent) {
@@ -259,17 +627,22 @@ var DependencyInjection = class _DependencyInjection {
       await this.loader.load(this.options.servicesYamlPath);
     }
     this.registerParentAliases();
+    this.applyOverrides();
     await this.container.compile();
   }
   getService(serviceName) {
-    const childServiceId = this.findConcreteChildServiceId(serviceName);
-    if (childServiceId) {
-      return this.container.get(childServiceId);
+    const overrideTokenId = this.overrideTokenIds.get(serviceName);
+    if (overrideTokenId) {
+      return this.container.get(overrideTokenId);
     }
     const aliasServiceId = this.findAliasServiceId(serviceName);
     if (aliasServiceId) {
       return this.container.get(aliasServiceId);
     }
+    const childServiceId = this.findConcreteChildServiceId(serviceName);
+    if (childServiceId) {
+      return this.container.get(childServiceId);
+    }
     const registeredServiceId = this.findRegisteredServiceId(serviceName);
     if (registeredServiceId) {
       return this.container.get(registeredServiceId);
@@ -303,7 +676,7 @@ var Kernel = class _Kernel {
     return stateContainer[_Kernel.stateKey];
   }
   static get configDirectory() {
-    return import_node_path2.default.resolve(_Kernel.rootDirectory, "config");
+    return import_node_path3.default.resolve(_Kernel.rootDirectory, "config");
   }
   static get consumers() {
     return _Kernel.getActiveKernel().consumers;
@@ -317,6 +690,9 @@ var Kernel = class _Kernel {
   static get logger() {
     return _Kernel.getActiveKernel().logger;
   }
+  static get active() {
+    return _Kernel.getActiveKernel();
+  }
   static get rootDirectory() {
     return process.cwd();
   }
@@ -327,7 +703,7 @@ var Kernel = class _Kernel {
     return _Kernel.getActiveKernel().schedulers;
   }
   static get sourceDirectory() {
-    return import_node_path2.default.resolve(_Kernel.rootDirectory, "src");
+    return import_node_path3.default.resolve(_Kernel.rootDirectory, "src");
   }
   static getActiveKernel() {
     if (!_Kernel.state.activeKernel) {
@@ -385,13 +761,21 @@ var Kernel = class _Kernel {
   get schedulers() {
     return this.schedulersList;
   }
-  async dependencyInjection() {
-    this.dependencyInjectionInstance = this.dependencyInjectionInstance ?? DependencyInjection.configure({
-      containerBuild: process.env.CONTAINER_BUILD === "true",
-      servicesYamlPath: this.options.servicesYamlPath ?? import_node_path2.default.resolve(_Kernel.configDirectory, "container", "services.yaml"),
-      sourceDirectory: this.options.sourceDirectory ?? _Kernel.sourceDirectory
-    });
+  getDependencyInjectionOptions(options = {}) {
+    return {
+      containerBuild: options.containerBuild ?? process.env.CONTAINER_BUILD === "true",
+      overrides: options.overrides ?? [],
+      servicesYamlPath: options.servicesYamlPath ?? this.options.servicesYamlPath ?? import_node_path3.default.resolve(_Kernel.configDirectory, "container", "services.yaml"),
+      sourceDirectory: options.sourceDirectory ?? this.options.sourceDirectory ?? _Kernel.sourceDirectory
+    };
+  }
+  async dependencyInjection(options = {}) {
+    _Kernel.state.activeKernel = this;
+    this.dependencyInjectionInstance = this.dependencyInjectionInstance ?? DependencyInjection.configure(
+      this.getDependencyInjectionOptions(options)
+    );
     await this.dependencyInjectionInstance.compile();
+    _Kernel.state.activeKernel = this;
   }
   getRoutes() {
     return this.routes;
@@ -483,6 +867,7 @@ var Route = class {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ExpressKernelServer,
+  HttpErrorHandler,
   Route,
   RoutePrefix
 });