@onebun/core 0.1.13 → 0.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onebun/core",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Core package for OneBun framework - decorators, DI, modules, controllers",
   "license": "LGPL-3.0",
   "author": "RemRyahirev",

package/src/module/module.test.ts

@@ -154,6 +154,94 @@ describe('OneBunModule', () => {
 
       expect(() => new OneBunModule(TestClass, mockLoggerLayer)).toThrow();
     });
+
+    test('should detect circular dependencies and provide detailed error message', () => {
+      const { registerDependencies } = require('../decorators/decorators');
+      const { Effect, Layer } = require('effect');
+      const { LoggerService } = require('@onebun/logger');
+
+      // Collect error messages
+      const errorMessages: string[] = [];
+
+      // Create mock logger that captures error messages
+      // Using Effect.sync to ensure the message is captured synchronously when Effect.runSync is called
+      const captureLogger = {
+        trace: () => Effect.sync(() => undefined),
+        debug: () => Effect.sync(() => undefined),
+        info: () => Effect.sync(() => undefined),
+        warn: () => Effect.sync(() => undefined),
+        error: (msg: string) =>
+          Effect.sync(() => {
+            errorMessages.push(msg);
+          }),
+        fatal: () => Effect.sync(() => undefined),
+        child: () => captureLogger,
+      };
+      const captureLoggerLayer = Layer.succeed(LoggerService, captureLogger);
+
+      // Create services - define all classes first
+      @Service()
+      class CircularServiceA {
+        getValue() {
+          return 'A';
+        }
+      }
+
+      @Service()
+      class CircularServiceB {
+        getValue() {
+          return 'B';
+        }
+      }
+
+      @Service()
+      class CircularServiceC {
+        getValue() {
+          return 'C';
+        }
+      }
+
+      // Now register circular dependencies manually: A -> B -> C -> A
+      registerDependencies(CircularServiceA, [CircularServiceC]);
+      registerDependencies(CircularServiceB, [CircularServiceA]);
+      registerDependencies(CircularServiceC, [CircularServiceB]);
+
+      @Module({
+        providers: [CircularServiceA, CircularServiceB, CircularServiceC],
+      })
+      class CircularModule {}
+
+      // Initialize module - should detect circular dependency
+      new OneBunModule(CircularModule, captureLoggerLayer);
+
+      // Verify error message was logged
+      expect(errorMessages.length).toBeGreaterThan(0);
+
+      // Find the circular dependency error message
+      const circularError = errorMessages.find((msg) =>
+        msg.includes('Circular dependency detected'),
+      );
+      expect(circularError).toBeDefined();
+
+      // Should contain module name
+      expect(circularError).toContain('CircularModule');
+
+      // Should contain "Unresolved services" section
+      expect(circularError).toContain('Unresolved services');
+
+      // Should contain at least one of the service names with their dependencies
+      const hasServiceInfo =
+        circularError!.includes('CircularServiceA') ||
+        circularError!.includes('CircularServiceB') ||
+        circularError!.includes('CircularServiceC');
+      expect(hasServiceInfo).toBe(true);
+
+      // Should contain "needs:" showing what dependencies are required
+      expect(circularError).toContain('needs:');
+
+      // Should contain "Dependency chain" showing the cycle
+      expect(circularError).toContain('Dependency chain');
+    });
   });
 
   describe('Module instance methods', () => {

package/src/module/module.ts

@@ -68,6 +68,7 @@ export class OneBunModule implements ModuleInstance {
   private controllers: Function[] = [];
   private controllerInstances: Map<Function, Controller> = new Map();
   private serviceInstances: Map<Context.Tag<unknown, unknown>, unknown> = new Map();
+  private pendingAsyncInits: Array<{ name: string; init: () => Promise<void> }> = [];
   private logger: SyncLogger;
   private config: IConfig<OneBunAppConfig>;
 
@@ -228,6 +229,7 @@ export class OneBunModule implements ModuleInstance {
     // Create services in dependency order
     const pendingProviders = [...metadata.providers.filter((p) => typeof p === 'function')];
     const createdServices = new Set<string>();
+    const unresolvedDeps = new Map<string, string[]>(); // Track unresolved dependencies for error reporting
     let iterations = 0;
     const maxIterations = pendingProviders.length * 2; // Prevent infinite loops
 
@@ -244,8 +246,11 @@ export class OneBunModule implements ModuleInstance {
         continue;
       }
 
-      // Use autoDetectDependencies to find dependencies from constructor
-      const detectedDeps = autoDetectDependencies(provider, availableServiceClasses);
+      // Use getConstructorParamTypes first (for @Inject and TypeScript metadata),
+      // then fallback to autoDetectDependencies (for constructor source analysis)
+      const detectedDeps =
+        getConstructorParamTypes(provider) ||
+        autoDetectDependencies(provider, availableServiceClasses);
       const dependencies: unknown[] = [];
       let allDependenciesResolved = true;
 
@@ -258,6 +263,12 @@ export class OneBunModule implements ModuleInstance {
             // Check if it's a service that hasn't been created yet
             const isServiceInModule = availableServiceClasses.has(depType.name);
             if (isServiceInModule && !createdServices.has(depType.name)) {
+              // Track unresolved dependency for error reporting
+              const deps = unresolvedDeps.get(provider.name) || [];
+              if (!deps.includes(depType.name)) {
+                deps.push(depType.name);
+                unresolvedDeps.set(provider.name, deps);
+              }
               // This dependency will be created later, defer this service
               allDependenciesResolved = false;
               pendingProviders.push(provider);
@@ -292,6 +303,19 @@ export class OneBunModule implements ModuleInstance {
             .initializeService(this.logger, this.config);
         }
 
+        // Track services that need async initialization
+        if (
+          serviceInstance &&
+          typeof serviceInstance === 'object' &&
+          'onAsyncInit' in serviceInstance &&
+          typeof (serviceInstance as { onAsyncInit: unknown }).onAsyncInit === 'function'
+        ) {
+          this.pendingAsyncInits.push({
+            name: provider.name,
+            init: () => (serviceInstance as { onAsyncInit: () => Promise<void> }).onAsyncInit(),
+          });
+        }
+
         this.serviceInstances.set(serviceMetadata.tag, serviceInstance);
         createdServices.add(provider.name);
         this.logger.debug(
@@ -303,7 +327,25 @@ export class OneBunModule implements ModuleInstance {
     }
 
     if (iterations >= maxIterations) {
-      this.logger.error('Possible circular dependency detected in services');
+      const unresolvedServices = pendingProviders
+        .filter((p) => typeof p === 'function')
+        .map((p) => p.name);
+
+      const details = unresolvedServices
+        .map((serviceName) => {
+          const deps = unresolvedDeps.get(serviceName) || [];
+
+          return `  - ${serviceName} -> needs: [${deps.join(', ')}]`;
+        })
+        .join('\n');
+
+      const dependencyChain = this.buildDependencyChain(unresolvedDeps, unresolvedServices);
+
+      this.logger.error(
+        `Circular dependency detected in module ${this.moduleClass.name}!\n` +
+          `Unresolved services:\n${details}\n` +
+          `Dependency chain: ${dependencyChain}`,
+      );
     }
   }
 
@@ -340,14 +382,12 @@ export class OneBunModule implements ModuleInstance {
    * Create controller instances and inject services
    */
   createControllerInstances(): Effect.Effect<unknown, never, void> {
-    const self = this;
-
-    return Effect.gen(function* (_) {
+    return Effect.sync(() => {
       // Services are already created in initModule via createServicesWithDI
       // Just need to set up controllers with DI
 
       // Get module metadata to access providers for controller dependency registration
-      const moduleMetadata = getModuleMetadata(self.moduleClass);
+      const moduleMetadata = getModuleMetadata(this.moduleClass);
       if (moduleMetadata && moduleMetadata.providers) {
         // Create map of available services for dependency resolution
         const availableServices = new Map<string, Function>();
@@ -360,7 +400,7 @@ export class OneBunModule implements ModuleInstance {
         }
 
         // Also add services from imported modules
-        for (const childModule of self.childModules) {
+        for (const childModule of this.childModules) {
           const childMetadata = getModuleMetadata(childModule.moduleClass);
           if (childMetadata?.exports) {
             for (const exported of childMetadata.exports) {
@@ -379,13 +419,13 @@ export class OneBunModule implements ModuleInstance {
         }
 
         // Automatically analyze and register dependencies for all controllers
-        for (const controllerClass of self.controllers) {
+        for (const controllerClass of this.controllers) {
           registerControllerDependencies(controllerClass, availableServices);
         }
       }
 
       // Now create controller instances with automatic dependency injection
-      self.createControllersWithDI();
+      this.createControllersWithDI();
     }).pipe(Effect.provide(this.rootLayer));
   }
 
@@ -467,11 +507,95 @@ export class OneBunModule implements ModuleInstance {
     return serviceInstance;
   }
 
+  /**
+   * Build a human-readable dependency chain for circular dependency error reporting
+   * Traverses the dependency graph to find and display the cycle
+   */
+  private buildDependencyChain(
+    unresolvedDeps: Map<string, string[]>,
+    unresolvedServices: string[],
+  ): string {
+    // Find cycle by traversing dependencies
+    const visited = new Set<string>();
+    const chain: string[] = [];
+
+    const findCycle = (service: string): boolean => {
+      if (visited.has(service)) {
+        chain.push(service);
+
+        return true;
+      }
+      visited.add(service);
+      chain.push(service);
+
+      const deps = unresolvedDeps.get(service) || [];
+      for (const dep of deps) {
+        if (unresolvedServices.includes(dep)) {
+          if (findCycle(dep)) {
+            return true;
+          }
+        }
+      }
+      chain.pop();
+
+      return false;
+    };
+
+    for (const service of unresolvedServices) {
+      visited.clear();
+      chain.length = 0;
+      if (findCycle(service)) {
+        return chain.join(' -> ');
+      }
+    }
+
+    // If no cycle found, just show all unresolved services
+    return unresolvedServices.join(' <-> ');
+  }
+
   /**
    * Setup the module and its dependencies
    */
   setup(): Effect.Effect<unknown, never, void> {
-    return this.createControllerInstances();
+    return this.runAsyncServiceInit().pipe(
+      // Also run async init for child modules
+      Effect.flatMap(() =>
+        Effect.forEach(this.childModules, (childModule) => childModule.runAsyncServiceInit(), {
+          discard: true,
+        }),
+      ),
+      // Then create controller instances
+      Effect.flatMap(() => this.createControllerInstances()),
+    );
+  }
+
+  /**
+   * Run async initialization for all services that need it
+   */
+  runAsyncServiceInit(): Effect.Effect<unknown, never, void> {
+    if (this.pendingAsyncInits.length === 0) {
+      return Effect.void;
+    }
+
+    this.logger.debug(`Running async initialization for ${this.pendingAsyncInits.length} service(s)`);
+
+    // Run all async inits in parallel
+    const initPromises = this.pendingAsyncInits.map(async ({ name, init }) => {
+      try {
+        await init();
+        this.logger.debug(`Service ${name} async initialization completed`);
+      } catch (error) {
+        this.logger.error(`Service ${name} async initialization failed: ${error}`);
+        throw error;
+      }
+    });
+
+    return Effect.promise(() => Promise.all(initPromises)).pipe(
+      Effect.map(() => {
+        // Clear the list after initialization
+        this.pendingAsyncInits = [];
+      }),
+    );
   }
 
   /**

package/src/module/service.ts

@@ -99,6 +99,16 @@ export class BaseService {
     this.logger.debug(`Service ${className} initialized`);
   }
 
+  /**
+   * Async initialization hook - called by the framework after initializeService()
+   * Override in subclasses that need async initialization (e.g., database connections)
+   * The framework will await this method before making the service available
+   * @internal
+   */
+  async onAsyncInit(): Promise<void> {
+    // Default: no async init needed
+  }
+
   /**
    * Check if service is initialized
    * @internal