@onebun/core 0.1.21 → 0.1.22

package/package.json

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

package/src/docs-examples.test.ts

@@ -1150,6 +1150,100 @@ describe('Lifecycle Hooks API Documentation Examples (docs/api/services.md)', ()
       await callOnApplicationDestroy(emptyObj, 'SIGTERM');
     });
   });
+
+  describe('Standalone Service Pattern (docs/api/services.md)', () => {
+    /**
+     * @source docs/api/services.md#lifecycle-hooks
+     * Standalone services (not injected anywhere) still have their
+     * onModuleInit called. This is useful for background workers,
+     * cron jobs, event listeners, etc.
+     */
+    it('should call onModuleInit for standalone services not injected anywhere', async () => {
+      const moduleMod = await import('./module/module');
+      const testUtils = await import('./testing/test-utils');
+      const effectLib = await import('effect');
+
+      let schedulerStarted = false;
+
+      // From docs: Standalone service pattern
+      @Service()
+      class TaskSchedulerService extends BaseService implements OnModuleInit {
+        async onModuleInit(): Promise<void> {
+          // Main work happens here — no need to be injected anywhere
+          schedulerStarted = true;
+          this.logger.info('Task scheduler started');
+        }
+      }
+
+      @Module({
+        providers: [TaskSchedulerService],
+        // No controllers use this service — it works on its own
+      })
+      class SchedulerModule {}
+
+      const mod = new moduleMod.OneBunModule(SchedulerModule, testUtils.makeMockLoggerLayer());
+      await effectLib.Effect.runPromise(mod.setup() as import('effect').Effect.Effect<unknown, never, never>);
+
+      // Scheduler was started even though nothing injected it
+      expect(schedulerStarted).toBe(true);
+    });
+
+    /**
+     * @source docs/api/services.md#lifecycle-hooks
+     * onModuleInit is called sequentially in dependency order:
+     * dependencies complete their init before dependents start theirs.
+     */
+    it('should call onModuleInit in dependency order so dependencies are fully initialized', async () => {
+      const moduleMod = await import('./module/module');
+      const testUtils = await import('./testing/test-utils');
+      const effectLib = await import('effect');
+      const decorators = await import('./decorators/decorators');
+
+      const initOrder: string[] = [];
+
+      @Service()
+      class DatabaseService extends BaseService implements OnModuleInit {
+        private ready = false;
+
+        async onModuleInit(): Promise<void> {
+          this.ready = true;
+          initOrder.push('database');
+        }
+
+        isReady(): boolean {
+          return this.ready;
+        }
+      }
+
+      @Service()
+      class CacheService extends BaseService implements OnModuleInit {
+        private db: DatabaseService;
+
+        constructor(db: DatabaseService) {
+          super();
+          this.db = db;
+        }
+
+        async onModuleInit(): Promise<void> {
+          // At this point, DatabaseService.onModuleInit has already completed
+          initOrder.push(`cache:db-ready=${this.db.isReady()}`);
+        }
+      }
+
+      decorators.registerDependencies(CacheService, [DatabaseService]);
+
+      @Module({
+        providers: [DatabaseService, CacheService],
+      })
+      class AppModule {}
+
+      const mod = new moduleMod.OneBunModule(AppModule, testUtils.makeMockLoggerLayer());
+      await effectLib.Effect.runPromise(mod.setup() as import('effect').Effect.Effect<unknown, never, never>);
+
+      // Database initialized first, then cache saw database was ready
+      expect(initOrder).toEqual(['database', 'cache:db-ready=true']);
+    });
+  });
 });
 
 describe('getService API Documentation Examples (docs/api/core.md)', () => {

package/src/module/module.test.ts

@@ -853,6 +853,188 @@ describe('OneBunModule', () => {
     });
   });
 
+  describe('Lifecycle hooks', () => {
+    const { clearGlobalModules } = require('../decorators/decorators');
+    const { clearGlobalServicesRegistry: clearRegistry, OneBunModule: ModuleClass } = require('./module');
+    const { OnModuleInit } = require('./lifecycle');
+
+    beforeEach(() => {
+      clearGlobalModules();
+      clearRegistry();
+    });
+
+    afterEach(() => {
+      clearGlobalModules();
+      clearRegistry();
+    });
+
+    test('should call onModuleInit for a service that is not injected anywhere', async () => {
+      let initCalled = false;
+
+      @Service()
+      class StandaloneService {
+        async onModuleInit(): Promise<void> {
+          initCalled = true;
+        }
+      }
+
+      @Module({
+        providers: [StandaloneService],
+        // No controllers, no exports — this service is not injected anywhere
+      })
+      class TestModule {}
+
+      const module = new ModuleClass(TestModule, mockLoggerLayer);
+      await Effect.runPromise(module.setup() as Effect.Effect<unknown, never, never>);
+
+      expect(initCalled).toBe(true);
+    });
+
+    test('should call onModuleInit for multiple standalone services', async () => {
+      const initLog: string[] = [];
+
+      @Service()
+      class WorkerServiceA {
+        async onModuleInit(): Promise<void> {
+          initLog.push('A');
+        }
+      }
+
+      @Service()
+      class WorkerServiceB {
+        async onModuleInit(): Promise<void> {
+          initLog.push('B');
+        }
+      }
+
+      @Service()
+      class WorkerServiceC {
+        async onModuleInit(): Promise<void> {
+          initLog.push('C');
+        }
+      }
+
+      @Module({
+        providers: [WorkerServiceA, WorkerServiceB, WorkerServiceC],
+      })
+      class TestModule {}
+
+      const module = new ModuleClass(TestModule, mockLoggerLayer);
+      await Effect.runPromise(module.setup() as Effect.Effect<unknown, never, never>);
+
+      expect(initLog).toContain('A');
+      expect(initLog).toContain('B');
+      expect(initLog).toContain('C');
+      expect(initLog.length).toBe(3);
+    });
+
+    test('should call onModuleInit for standalone service in a child module', async () => {
+      let childInitCalled = false;
+
+      @Service()
+      class ChildStandaloneService {
+        async onModuleInit(): Promise<void> {
+          childInitCalled = true;
+        }
+      }
+
+      @Module({
+        providers: [ChildStandaloneService],
+      })
+      class ChildModule {}
+
+      @Module({
+        imports: [ChildModule],
+      })
+      class RootModule {}
+
+      const module = new ModuleClass(RootModule, mockLoggerLayer);
+      await Effect.runPromise(module.setup() as Effect.Effect<unknown, never, never>);
+
+      expect(childInitCalled).toBe(true);
+    });
+
+    test('should call onModuleInit sequentially in dependency order', async () => {
+      const initLog: string[] = [];
+      const { registerDependencies } = require('../decorators/decorators');
+
+      @Service()
+      class DependencyService {
+        async onModuleInit(): Promise<void> {
+          // Simulate async work to make ordering matter
+          await new Promise<void>((resolve) => {
+            setTimeout(resolve, 5);
+          });
+          initLog.push('dependency-completed');
+        }
+
+        getValue() {
+          return 42;
+        }
+      }
+
+      @Service()
+      class DependentService {
+        async onModuleInit(): Promise<void> {
+          initLog.push('dependent-started');
+        }
+      }
+
+      // Register DependentService -> DependencyService dependency
+      registerDependencies(DependentService, [DependencyService]);
+
+      @Module({
+        providers: [DependencyService, DependentService],
+      })
+      class TestModule {}
+
+      const module = new ModuleClass(TestModule, mockLoggerLayer);
+      await Effect.runPromise(module.setup() as Effect.Effect<unknown, never, never>);
+
+      // DependencyService.onModuleInit must complete BEFORE DependentService.onModuleInit starts
+      expect(initLog).toEqual(['dependency-completed', 'dependent-started']);
+    });
+
+    test('should have dependencies already injected when onModuleInit is called', async () => {
+      let depValueInInit: number | null = null;
+      const { registerDependencies } = require('../decorators/decorators');
+
+      @Service()
+      class ConfigService {
+        getPort() {
+          return 8080;
+        }
+      }
+
+      @Service()
+      class ServerService {
+        private configService: ConfigService;
+
+        constructor(configService: ConfigService) {
+          this.configService = configService;
+        }
+
+        async onModuleInit(): Promise<void> {
+          // At this point configService should already be injected
+          depValueInInit = this.configService.getPort();
+        }
+      }
+
+      registerDependencies(ServerService, [ConfigService]);
+
+      @Module({
+        providers: [ConfigService, ServerService],
+      })
+      class TestModule {}
+
+      const module = new ModuleClass(TestModule, mockLoggerLayer);
+      await Effect.runPromise(module.setup() as Effect.Effect<unknown, never, never>);
+
+      expect(depValueInInit).not.toBeNull();
+      expect(depValueInInit as unknown as number).toBe(8080);
+    });
+  });
+
   describe('Module DI scoping (exports only for cross-module)', () => {
     const {
       Controller: ControllerDecorator,

package/src/module/module.ts

@@ -555,7 +555,10 @@ export class OneBunModule implements ModuleInstance {
   }
 
   /**
-   * Call onModuleInit lifecycle hook for all services that implement it
+   * Call onModuleInit lifecycle hook for all services that implement it.
+   * Hooks are called sequentially in dependency order (dependencies first),
+   * so each service's onModuleInit completes before its dependents' onModuleInit starts.
+   * This is called for ALL services in providers, even if they are not injected anywhere.
    */
   callServicesOnModuleInit(): Effect.Effect<unknown, never, void> {
     if (this.pendingServiceInits.length === 0) {
@@ -564,25 +567,23 @@ export class OneBunModule implements ModuleInstance {
 
     this.logger.debug(`Calling onModuleInit for ${this.pendingServiceInits.length} service(s)`);
 
-    // Run all service onModuleInit hooks sequentially
-    const initPromises = this.pendingServiceInits.map(async ({ name, instance }) => {
-      try {
-        if (hasOnModuleInit(instance)) {
-          await instance.onModuleInit();
+    return Effect.promise(async () => {
+      // Run onModuleInit hooks sequentially in dependency order
+      // (pendingServiceInits is already ordered: dependencies first)
+      for (const { name, instance } of this.pendingServiceInits) {
+        try {
+          if (hasOnModuleInit(instance)) {
+            await instance.onModuleInit();
+          }
+          this.logger.debug(`Service ${name} onModuleInit completed`);
+        } catch (error) {
+          this.logger.error(`Service ${name} onModuleInit failed: ${error}`);
+          throw error;
         }
-        this.logger.debug(`Service ${name} onModuleInit completed`);
-      } catch (error) {
-        this.logger.error(`Service ${name} onModuleInit failed: ${error}`);
-        throw error;
       }
+      // Clear the list after initialization
+      this.pendingServiceInits = [];
     });
-
-    return Effect.promise(() => Promise.all(initPromises)).pipe(
-      Effect.map(() => {
-        // Clear the list after initialization
-        this.pendingServiceInits = [];
-      }),
-    );
   }
 
   /**