@onebun/core 0.1.21 → 0.1.23

package/package.json

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

package/src/docs-examples.test.ts

@@ -816,7 +816,7 @@ describe('Services API Documentation Examples', () => {
       @Service()
       class UserService extends BaseService {
         // Dependencies are auto-injected via constructor
-        // Logger and config are auto-injected via initializeService()
+        // Logger and config are available immediately after super()
         constructor(private repository: UserRepository) {
           super();
         }
@@ -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

@@ -851,6 +851,288 @@ describe('OneBunModule', () => {
       expect(apiService).toBeDefined();
       expect((apiService as ApiService).getConnectionTimeout()).toBe(5000);
     });
+
+    /**
+     * Test that this.config and this.logger are available in the service constructor
+     * when the service is created through the DI system (via ambient init context).
+     */
+    test('should have this.config and this.logger available in constructor via DI', () => {
+      let configInConstructor: unknown = undefined;
+      let loggerInConstructor: unknown = undefined;
+
+      @Service()
+      class ConfigAwareService extends BaseServiceClass {
+        constructor() {
+          super();
+          configInConstructor = this.config;
+          loggerInConstructor = this.logger;
+        }
+      }
+
+      @ModuleDecorator({
+        providers: [ConfigAwareService],
+      })
+      class TestModule {}
+
+      // Initialize module — this triggers DI and service creation
+      new ModuleInstance(TestModule, mockLoggerLayer);
+
+      // config and logger should have been available in the constructor
+      expect(configInConstructor).toBeDefined();
+      expect(loggerInConstructor).toBeDefined();
+    });
+
+    /**
+     * Test that this.config.get() works in the constructor for services created via DI
+     */
+    test('should allow config.get() in service constructor via DI', () => {
+      @Service()
+      class ServiceWithConfigInConstructor extends BaseServiceClass {
+        readonly configValue: unknown;
+
+        constructor() {
+          super();
+          // Config should be available here via init context
+          this.configValue = this.config;
+        }
+
+        getConfigValue() {
+          return this.configValue;
+        }
+      }
+
+      @ModuleDecorator({
+        providers: [ServiceWithConfigInConstructor],
+      })
+      class TestModule {}
+
+      const module = new ModuleInstance(TestModule, mockLoggerLayer);
+
+      const { getServiceTag } = require('./service');
+      const tag = getServiceTag(ServiceWithConfigInConstructor);
+      const service = module.getServiceInstance(tag) as ServiceWithConfigInConstructor;
+
+      expect(service).toBeDefined();
+      // configValue was captured in constructor — should not be undefined
+      expect(service.getConfigValue()).toBeDefined();
+    });
+
+    /**
+     * Test that this.config is available in constructor of a service with dependencies
+     */
+    test('should have this.config in constructor of service with dependencies', () => {
+      let configAvailable = false;
+
+      @Service()
+      class DependencyService {
+        getValue() {
+          return 42;
+        }
+      }
+
+      @Service()
+      class MainService extends BaseServiceClass {
+        constructor(private dep: DependencyService) {
+          super();
+          configAvailable = this.config !== undefined;
+        }
+
+        getDep() {
+          return this.dep.getValue();
+        }
+      }
+
+      @ModuleDecorator({
+        providers: [DependencyService, MainService],
+      })
+      class TestModule {}
+
+      new ModuleInstance(TestModule, mockLoggerLayer);
+
+      expect(configAvailable).toBe(true);
+    });
+  });
+
+  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)', () => {

package/src/module/module.ts

@@ -36,7 +36,11 @@ import {
   hasBeforeApplicationDestroy,
   hasOnApplicationDestroy,
 } from './lifecycle';
-import { getServiceMetadata, getServiceTag } from './service';
+import {
+  BaseService,
+  getServiceMetadata,
+  getServiceTag,
+} from './service';
 
 /**
  * Global services registry
@@ -290,13 +294,23 @@ export class OneBunModule implements ModuleInstance {
         continue;
       }
 
-      // Create service instance with resolved dependencies (without logger/config in constructor)
+      // Create service instance with resolved dependencies.
+      // Set ambient init context so BaseService constructor can pick up logger/config,
+      // making them available immediately after super() in subclass constructors.
       try {
         const serviceConstructor = provider as new (...args: unknown[]) => unknown;
-        const serviceInstance = new serviceConstructor(...dependencies);
 
-        // Initialize service with logger and config if it has initializeService method
-        // This is the pattern used by BaseService
+        BaseService.setInitContext(this.logger, this.config);
+        let serviceInstance: unknown;
+        try {
+          serviceInstance = new serviceConstructor(...dependencies);
+        } finally {
+          BaseService.clearInitContext();
+        }
+
+        // Fallback: call initializeService for services that have it but were not
+        // initialized via the constructor (e.g., services not extending BaseService
+        // but implementing initializeService manually, or for backwards compatibility).
         if (
           serviceInstance &&
           typeof serviceInstance === 'object' &&
@@ -555,7 +569,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 +581,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 = [];
-      }),
-    );
   }
 
   /**

package/src/module/service.test.ts

@@ -165,6 +165,111 @@ describe('BaseService', () => {
     });
   });
 
+  describe('Initialization via static init context (constructor)', () => {
+    test('should initialize service via static init context in constructor', () => {
+      class TestService extends BaseService {
+        configAvailableInConstructor = false;
+        loggerAvailableInConstructor = false;
+
+        constructor() {
+          super();
+          this.configAvailableInConstructor = this.config !== undefined;
+          this.loggerAvailableInConstructor = this.logger !== undefined;
+        }
+      }
+
+      // Set init context before construction (as the framework does)
+      BaseService.setInitContext(mockLogger, mockConfig);
+      let service: TestService;
+      try {
+        service = new TestService();
+      } finally {
+        BaseService.clearInitContext();
+      }
+
+      expect(service.isInitialized).toBe(true);
+      expect(service.configAvailableInConstructor).toBe(true);
+      expect(service.loggerAvailableInConstructor).toBe(true);
+      expect((service as any).config).toBe(mockConfig);
+    });
+
+    test('should allow using config.get() in constructor when init context is set', () => {
+      class TestService extends BaseService {
+        readonly dbHost: string;
+
+        constructor() {
+          super();
+          this.dbHost = this.config.get('database.host') as string;
+        }
+      }
+
+      BaseService.setInitContext(mockLogger, mockConfig);
+      let service: TestService;
+      try {
+        service = new TestService();
+      } finally {
+        BaseService.clearInitContext();
+      }
+
+      expect(service.dbHost).toBe('localhost');
+    });
+
+    test('should create child logger with correct className in constructor', () => {
+      class MyCustomService extends BaseService {}
+
+      BaseService.setInitContext(mockLogger, mockConfig);
+      try {
+        new MyCustomService();
+      } finally {
+        BaseService.clearInitContext();
+      }
+
+      expect(mockLogger.child).toHaveBeenCalledWith({ className: 'MyCustomService' });
+    });
+
+    test('should not initialize if no init context is set', () => {
+      // Ensure context is clear
+      BaseService.clearInitContext();
+
+      class TestService extends BaseService {}
+      const service = new TestService();
+
+      expect(service.isInitialized).toBe(false);
+    });
+
+    test('initializeService should be a no-op if already initialized via init context', () => {
+      class TestService extends BaseService {}
+
+      BaseService.setInitContext(mockLogger, mockConfig);
+      let service: TestService;
+      try {
+        service = new TestService();
+      } finally {
+        BaseService.clearInitContext();
+      }
+
+      expect(service.isInitialized).toBe(true);
+
+      // Call initializeService again — should be a no-op
+      const otherLogger = { ...mockLogger, child: mock(() => ({ ...mockLogger })) };
+      const otherConfig = createMockConfig({ other: 'config' });
+      service.initializeService(otherLogger, otherConfig);
+
+      // Should still have original config (no reinit)
+      expect((service as any).config).toBe(mockConfig);
+    });
+
+    test('clearInitContext should prevent subsequent constructors from picking up context', () => {
+      BaseService.setInitContext(mockLogger, mockConfig);
+      BaseService.clearInitContext();
+
+      class TestService extends BaseService {}
+      const service = new TestService();
+
+      expect(service.isInitialized).toBe(false);
+    });
+  });
+
   describe('Error handling edge cases', () => {
     test('should handle complex effect scenarios', async () => {
       class TestService extends BaseService {

package/src/module/service.ts

@@ -19,8 +19,9 @@ const META_SERVICES = new Map<
 /**
  * Service decorator
  * Registers the class as a service with an optional Effect Context tag.
- * Services extending BaseService will have logger and config injected
- * via the initializeService method called by the module after instantiation.
+ * Services extending BaseService will have logger and config available
+ * immediately after super() in the constructor (via ambient init context),
+ * as well as through the initializeService fallback method.
  * 
  * @param tag - Optional Effect Context tag for the service
  */
@@ -62,7 +63,26 @@ export function getServiceTag<T>(serviceClass: new (...args: unknown[]) => T): C
 }
 
 /**
- * Base service class that provides utility methods for working with Effect
+ * Base service class that provides utility methods for working with Effect.
+ *
+ * Services extending BaseService have `this.config` and `this.logger` available
+ * immediately after `super()` in the constructor when created through the framework DI.
+ * The framework sets an ambient init context before calling the constructor, and
+ * BaseService reads from it in `super()`.
+ *
+ * @example
+ * ```typescript
+ * @Service()
+ * class MyService extends BaseService {
+ *   private readonly baseUrl: string;
+ *
+ *   constructor(private dep: SomeDep) {
+ *     super();
+ *     // this.config and this.logger are available here!
+ *     this.baseUrl = this.config.get('api.baseUrl');
+ *   }
+ * }
+ * ```
  */
 export class BaseService {
   // Logger instance with service class name as context
@@ -73,12 +93,55 @@ export class BaseService {
   private _initialized = false;
 
   /**
-   * Initialize service with logger and config (called by the framework)
+   * Ambient init context set by the framework before service construction.
+   * This allows BaseService constructor to pick up logger and config
+   * so they are available immediately after super() in subclass constructors.
+   * @internal
+   */
+  private static _initContext: { logger: SyncLogger; config: IConfig<OneBunAppConfig> } | null =
+    null;
+
+  /**
+   * Set the ambient init context before constructing a service.
+   * Called by the framework (OneBunModule) before `new ServiceClass(...)`.
+   * @internal
+   */
+  static setInitContext(logger: SyncLogger, config: IConfig<OneBunAppConfig>): void {
+    BaseService._initContext = { logger, config };
+  }
+
+  /**
+   * Clear the ambient init context after service construction.
+   * Called by the framework (OneBunModule) after `new ServiceClass(...)`.
+   * @internal
+   */
+  static clearInitContext(): void {
+    BaseService._initContext = null;
+  }
+
+  constructor() {
+    // Pick up logger and config from ambient init context if available.
+    // This makes this.config and this.logger available immediately after super()
+    // in subclass constructors.
+    if (BaseService._initContext) {
+      const { logger, config } = BaseService._initContext;
+      const className = this.constructor.name;
+      this.logger = logger.child({ className });
+      this.config = config;
+      this._initialized = true;
+    }
+  }
+
+  /**
+   * Initialize service with logger and config (called by the framework).
+   * This is a fallback for services not constructed through the DI system
+   * (e.g., in tests or when created manually). If the service was already
+   * initialized via the constructor init context, this is a no-op.
    * @internal
    */
   initializeService(logger: SyncLogger, config: IConfig<OneBunAppConfig>): void {
     if (this._initialized) {
-      return; // Already initialized
+      return; // Already initialized (via constructor or previous call)
     }
 
     const className = this.constructor.name;