@onebun/core 0.1.18 → 0.1.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onebun/core",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "Core package for OneBun framework - decorators, DI, modules, controllers",
   "license": "LGPL-3.0",
   "author": "RemRyahirev",
@@ -41,7 +41,7 @@
   "dependencies": {
     "effect": "^3.13.10",
     "arktype": "^2.0.0",
-    "@onebun/logger": "^0.1.5",
+    "@onebun/logger": "^0.1.6",
     "@onebun/envs": "^0.1.4",
     "@onebun/metrics": "^0.1.6",
     "@onebun/requests": "^0.1.3",

package/src/application/application.test.ts

@@ -826,7 +826,7 @@ describe('OneBunApplication', () => {
       await expect(app.start()).resolves.toBeUndefined();
     });
 
-    test('should stop server when running', () => {
+    test('should stop server when running', async () => {
       @Module({})
       class TestModule {}
 
@@ -838,20 +838,20 @@ describe('OneBunApplication', () => {
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       (app as any).server = mockServer;
 
-      app.stop();
+      await app.stop();
 
       expect(mockServer.stop).toHaveBeenCalled();
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       expect((app as any).server).toBeNull();
     });
 
-    test('should handle stop when server is not running', () => {
+    test('should handle stop when server is not running', async () => {
       @Module({})
       class TestModule {}
 
       const app = createTestApp(TestModule);
 
-      expect(() => app.stop()).not.toThrow();
+      await expect(app.stop()).resolves.toBeUndefined();
     });
   });
 

package/src/application/application.ts

@@ -13,6 +13,7 @@ import {
   type Logger,
   LoggerService,
   makeLogger,
+  makeLoggerFromOptions,
   type SyncLogger,
 } from '@onebun/logger';
 import {
@@ -191,8 +192,12 @@ export class OneBunApplication {
       this.config = new NotInitializedConfig();
     }
 
-    // Use provided logger layer or create a default one
-    const loggerLayer = this.options.loggerLayer || makeLogger();
+    // Use provided logger layer, or create from options, or use default
+    // Priority: loggerLayer > loggerOptions > env variables > NODE_ENV defaults
+    const loggerLayer = this.options.loggerLayer
+      ?? (this.options.loggerOptions
+        ? makeLoggerFromOptions(this.options.loggerOptions)
+        : makeLogger());
 
     // Initialize logger with application class name as context
     const effectLogger = Effect.runSync(
@@ -502,6 +507,12 @@ export class OneBunApplication {
         }
       }
 
+      // Call onApplicationInit lifecycle hook for all services and controllers
+      if (this.rootModule.callOnApplicationInit) {
+        await this.rootModule.callOnApplicationInit();
+        this.logger.debug('Application initialization hooks completed');
+      }
+
       // Get metrics path
       const metricsPath = this.options.metrics?.path || '/metrics';
 
@@ -1214,11 +1225,18 @@ export class OneBunApplication {
    * Stop the application with graceful shutdown
    * @param options - Shutdown options
    */
-  async stop(options?: { closeSharedRedis?: boolean }): Promise<void> {
+  async stop(options?: { closeSharedRedis?: boolean; signal?: string }): Promise<void> {
     const closeRedis = options?.closeSharedRedis ?? true;
+    const signal = options?.signal;
 
     this.logger.info('Stopping OneBun application...');
 
+    // Call beforeApplicationDestroy lifecycle hook
+    if (this.rootModule.callBeforeApplicationDestroy) {
+      this.logger.debug('Calling beforeApplicationDestroy hooks');
+      await this.rootModule.callBeforeApplicationDestroy(signal);
+    }
+
     // Cleanup WebSocket resources
     if (this.wsHandler) {
       this.logger.debug('Cleaning up WebSocket handler');
@@ -1247,12 +1265,24 @@ export class OneBunApplication {
       this.logger.debug('HTTP server stopped');
     }
 
+    // Call onModuleDestroy lifecycle hook
+    if (this.rootModule.callOnModuleDestroy) {
+      this.logger.debug('Calling onModuleDestroy hooks');
+      await this.rootModule.callOnModuleDestroy();
+    }
+
     // Close shared Redis connection if configured and requested
     if (closeRedis && SharedRedisProvider.isConnected()) {
       this.logger.debug('Disconnecting shared Redis');
       await SharedRedisProvider.disconnect();
     }
 
+    // Call onApplicationDestroy lifecycle hook
+    if (this.rootModule.callOnApplicationDestroy) {
+      this.logger.debug('Calling onApplicationDestroy hooks');
+      await this.rootModule.callOnApplicationDestroy(signal);
+    }
+
     this.logger.info('OneBun application stopped');
   }
 
@@ -1440,7 +1470,7 @@ export class OneBunApplication {
   enableGracefulShutdown(): void {
     const shutdown = async (signal: string) => {
       this.logger.info(`Received ${signal}, initiating graceful shutdown...`);
-      await this.stop();
+      await this.stop({ signal });
       process.exit(0);
     };
 
@@ -1469,4 +1499,36 @@ export class OneBunApplication {
   getHttpUrl(): string {
     return `http://${this.options.host}:${this.options.port}`;
   }
+
+  /**
+   * Get a service instance by class from the module container.
+   * Useful for accessing services outside of the request context.
+   * 
+   * @param serviceClass - The service class to get
+   * @returns The service instance
+   * @throws Error if service is not found
+   * 
+   * @example
+   * ```typescript
+   * const app = new OneBunApplication(AppModule, options);
+   * await app.start();
+   * 
+   * const userService = app.getService(UserService);
+   * await userService.performBackgroundTask();
+   * ```
+   */
+  getService<T>(serviceClass: new (...args: unknown[]) => T): T {
+    if (!this.rootModule.getServiceByClass) {
+      throw new Error('Module does not support getServiceByClass');
+    }
+
+    const service = this.rootModule.getServiceByClass(serviceClass);
+    if (!service) {
+      throw new Error(
+        `Service ${serviceClass.name} not found. Make sure it's registered in the module's providers.`,
+      );
+    }
+
+    return service;
+  }
 }

package/src/application/multi-service-application.ts

@@ -12,6 +12,7 @@ import {
   type Logger,
   LoggerService,
   makeLogger,
+  parseLogLevel,
   type SyncLogger,
 } from '@onebun/logger';
 
@@ -201,9 +202,9 @@ export class MultiServiceApplication<TServices extends ServicesMap = ServicesMap
           ...this.options.envOptions,
           valueOverrides: resolvedOverrides,
         },
-        // Logger configuration - use minLevel if provided
-        loggerLayer: mergedOptions.logger?.minLevel
-          ? makeLogger({ minLevel: this.getLogLevel(mergedOptions.logger.minLevel) })
+        // Logger configuration - use loggerOptions if minLevel provided
+        loggerOptions: mergedOptions.logger?.minLevel
+          ? { minLevel: parseLogLevel(mergedOptions.logger.minLevel) }
           : undefined,
         metrics: {
           ...mergedOptions.metrics,
@@ -316,24 +317,4 @@ export class MultiServiceApplication<TServices extends ServicesMap = ServicesMap
   getLogger(): SyncLogger {
     return this.logger;
   }
-
-  /**
-   * Convert log level string to numeric LogLevel value.
-   * LogLevel values: Fatal=60, Error=50, Warning=40, Info=30, Debug=20, Trace=10
-   */
-  private getLogLevel(level: string): number {
-    /* eslint-disable @typescript-eslint/no-magic-numbers */
-    const LOG_LEVEL_INFO = 30;
-    const levelMap: Record<string, number> = {
-      fatal: 60,
-      error: 50,
-      warning: 40,
-      info: LOG_LEVEL_INFO,
-      debug: 20,
-      trace: 10,
-    };
-
-    return levelMap[level.toLowerCase()] ?? LOG_LEVEL_INFO;
-    /* eslint-enable @typescript-eslint/no-magic-numbers */
-  }
 }

package/src/docs-examples.test.ts

@@ -26,6 +26,13 @@ import type {
   WsExecutionContext,
   WsServerType,
 } from './';
+import type {
+  OnModuleInit,
+  OnApplicationInit,
+  OnModuleDestroy,
+  BeforeApplicationDestroy,
+  OnApplicationDestroy,
+} from './';
 import type { SseEvent, SseGenerator } from './types';
 import type { ServerWebSocket } from 'bun';
 
@@ -877,6 +884,345 @@ describe('Services API Documentation Examples', () => {
   });
 });
 
+describe('Lifecycle Hooks API Documentation Examples (docs/api/services.md)', () => {
+  describe('OnModuleInit Interface', () => {
+    /**
+     * @source docs/api/services.md#lifecycle-hooks
+     */
+    it('should implement OnModuleInit interface', () => {
+      // From docs: OnModuleInit example
+      @Service()
+      class DatabaseService extends BaseService implements OnModuleInit {
+        private connection: unknown = null;
+
+        async onModuleInit(): Promise<void> {
+          // Called after service instantiation and DI
+          this.connection = { connected: true };
+          this.logger.info('Database connected');
+        }
+
+        isConnected(): boolean {
+          return this.connection !== null;
+        }
+      }
+
+      expect(DatabaseService).toBeDefined();
+      // Verify method exists
+      const service = new DatabaseService();
+      expect(typeof service.onModuleInit).toBe('function');
+    });
+  });
+
+  describe('OnApplicationInit Interface', () => {
+    /**
+     * @source docs/api/services.md#lifecycle-hooks
+     */
+    it('should implement OnApplicationInit interface', () => {
+      // From docs: OnApplicationInit example
+      @Service()
+      class CacheService extends BaseService implements OnApplicationInit {
+        async onApplicationInit(): Promise<void> {
+          // Called after all modules initialized, before HTTP server starts
+          this.logger.info('Warming up cache');
+        }
+      }
+
+      expect(CacheService).toBeDefined();
+      const service = new CacheService();
+      expect(typeof service.onApplicationInit).toBe('function');
+    });
+  });
+
+  describe('OnModuleDestroy Interface', () => {
+    /**
+     * @source docs/api/services.md#lifecycle-hooks
+     */
+    it('should implement OnModuleDestroy interface', () => {
+      // From docs: OnModuleDestroy example
+      @Service()
+      class ConnectionService extends BaseService implements OnModuleDestroy {
+        async onModuleDestroy(): Promise<void> {
+          // Called during shutdown, after HTTP server stops
+          this.logger.info('Closing connections');
+        }
+      }
+
+      expect(ConnectionService).toBeDefined();
+      const service = new ConnectionService();
+      expect(typeof service.onModuleDestroy).toBe('function');
+    });
+  });
+
+  describe('BeforeApplicationDestroy Interface', () => {
+    /**
+     * @source docs/api/services.md#lifecycle-hooks
+     */
+    it('should implement BeforeApplicationDestroy interface', () => {
+      // From docs: BeforeApplicationDestroy example
+      @Service()
+      class GracefulService extends BaseService implements BeforeApplicationDestroy {
+        beforeApplicationDestroy(signal?: string): void {
+          // Called at the very start of shutdown
+          this.logger.info(`Shutdown initiated by signal: ${signal || 'unknown'}`);
+        }
+      }
+
+      expect(GracefulService).toBeDefined();
+      const service = new GracefulService();
+      expect(typeof service.beforeApplicationDestroy).toBe('function');
+    });
+  });
+
+  describe('OnApplicationDestroy Interface', () => {
+    /**
+     * @source docs/api/services.md#lifecycle-hooks
+     */
+    it('should implement OnApplicationDestroy interface', () => {
+      // From docs: OnApplicationDestroy example
+      @Service()
+      class CleanupService extends BaseService implements OnApplicationDestroy {
+        async onApplicationDestroy(signal?: string): Promise<void> {
+          // Called at the very end of shutdown
+          this.logger.info(`Final cleanup, signal: ${signal || 'unknown'}`);
+        }
+      }
+
+      expect(CleanupService).toBeDefined();
+      const service = new CleanupService();
+      expect(typeof service.onApplicationDestroy).toBe('function');
+    });
+  });
+
+  describe('Multiple Lifecycle Hooks', () => {
+    /**
+     * @source docs/api/services.md#lifecycle-hooks
+     */
+    it('should implement multiple lifecycle interfaces', () => {
+      // From docs: Complete lifecycle example
+      @Service()
+      class FullLifecycleService extends BaseService 
+        implements OnModuleInit, OnApplicationInit, OnModuleDestroy, BeforeApplicationDestroy, OnApplicationDestroy {
+        
+        async onModuleInit(): Promise<void> {
+          this.logger.info('Service initialized');
+        }
+
+        async onApplicationInit(): Promise<void> {
+          this.logger.info('Application initialized');
+        }
+
+        beforeApplicationDestroy(signal?: string): void {
+          this.logger.info(`Shutdown starting: ${signal}`);
+        }
+
+        async onModuleDestroy(): Promise<void> {
+          this.logger.info('Module destroying');
+        }
+
+        async onApplicationDestroy(signal?: string): Promise<void> {
+          this.logger.info(`Application destroyed: ${signal}`);
+        }
+      }
+
+      expect(FullLifecycleService).toBeDefined();
+      const service = new FullLifecycleService();
+      expect(typeof service.onModuleInit).toBe('function');
+      expect(typeof service.onApplicationInit).toBe('function');
+      expect(typeof service.beforeApplicationDestroy).toBe('function');
+      expect(typeof service.onModuleDestroy).toBe('function');
+      expect(typeof service.onApplicationDestroy).toBe('function');
+    });
+  });
+
+  describe('Controller Lifecycle Hooks', () => {
+    /**
+     * @source docs/api/controllers.md#lifecycle-hooks
+     */
+    it('should implement lifecycle hooks in controllers', () => {
+      // From docs: Controller lifecycle hooks example
+      @Controller('/api')
+      class ApiController extends BaseController implements OnModuleInit, OnModuleDestroy {
+        async onModuleInit(): Promise<void> {
+          this.logger.info('Controller initialized');
+        }
+
+        async onModuleDestroy(): Promise<void> {
+          this.logger.info('Controller destroying');
+        }
+
+        @Get('/test')
+        test(): Response {
+          return this.success({ message: 'test' });
+        }
+      }
+
+      expect(ApiController).toBeDefined();
+      const controller = new ApiController();
+      expect(typeof controller.onModuleInit).toBe('function');
+      expect(typeof controller.onModuleDestroy).toBe('function');
+    });
+  });
+
+  describe('Lifecycle Helper Functions', () => {
+    /**
+     * Tests for lifecycle helper functions
+     */
+    it('should detect hasOnModuleInit correctly', () => {
+      const withHook = { onModuleInit: () => Promise.resolve() };
+      const withoutHook = { someOtherMethod: () => 'nothing' };
+
+      expect(hasOnModuleInit(withHook)).toBe(true);
+      expect(hasOnModuleInit(withoutHook)).toBe(false);
+      expect(hasOnModuleInit(null)).toBe(false);
+      expect(hasOnModuleInit(undefined)).toBe(false);
+    });
+
+    it('should detect hasOnApplicationInit correctly', () => {
+      const withHook = { onApplicationInit: () => Promise.resolve() };
+      const withoutHook = {};
+
+      expect(hasOnApplicationInit(withHook)).toBe(true);
+      expect(hasOnApplicationInit(withoutHook)).toBe(false);
+    });
+
+    it('should detect hasOnModuleDestroy correctly', () => {
+      const withHook = { onModuleDestroy: () => Promise.resolve() };
+      const withoutHook = {};
+
+      expect(hasOnModuleDestroy(withHook)).toBe(true);
+      expect(hasOnModuleDestroy(withoutHook)).toBe(false);
+    });
+
+    it('should detect hasBeforeApplicationDestroy correctly', () => {
+      const withHook = { beforeApplicationDestroy: () => undefined };
+      const withoutHook = {};
+
+      expect(hasBeforeApplicationDestroy(withHook)).toBe(true);
+      expect(hasBeforeApplicationDestroy(withoutHook)).toBe(false);
+    });
+
+    it('should detect hasOnApplicationDestroy correctly', () => {
+      const withHook = { onApplicationDestroy: () => Promise.resolve() };
+      const withoutHook = {};
+
+      expect(hasOnApplicationDestroy(withHook)).toBe(true);
+      expect(hasOnApplicationDestroy(withoutHook)).toBe(false);
+    });
+
+    it('should call lifecycle hooks safely', async () => {
+      const results: string[] = [];
+      
+      const service = {
+        async onModuleInit() {
+          results.push('init'); 
+        },
+        async onApplicationInit() {
+          results.push('appInit'); 
+        },
+        beforeApplicationDestroy(signal?: string) {
+          results.push(`before:${signal}`); 
+        },
+        async onModuleDestroy() {
+          results.push('destroy'); 
+        },
+        async onApplicationDestroy(signal?: string) {
+          results.push(`appDestroy:${signal}`); 
+        },
+      };
+
+      await callOnModuleInit(service);
+      await callOnApplicationInit(service);
+      await callBeforeApplicationDestroy(service, 'SIGTERM');
+      await callOnModuleDestroy(service);
+      await callOnApplicationDestroy(service, 'SIGTERM');
+
+      expect(results).toEqual(['init', 'appInit', 'before:SIGTERM', 'destroy', 'appDestroy:SIGTERM']);
+    });
+
+    it('should not throw when calling hooks on objects without them', async () => {
+      const emptyObj = {};
+
+      // These should not throw
+      await callOnModuleInit(emptyObj);
+      await callOnApplicationInit(emptyObj);
+      await callBeforeApplicationDestroy(emptyObj, 'SIGTERM');
+      await callOnModuleDestroy(emptyObj);
+      await callOnApplicationDestroy(emptyObj, 'SIGTERM');
+    });
+  });
+});
+
+describe('getService API Documentation Examples (docs/api/core.md)', () => {
+  /**
+   * @source docs/api/core.md#accessing-services-outside-of-requests
+   */
+  it('should have getService method on OneBunApplication', () => {
+    @Module({ controllers: [] })
+    class AppModule {}
+
+    const app = new OneBunApplication(AppModule, {
+      loggerLayer: makeMockLoggerLayer(),
+    });
+
+    expect(typeof app.getService).toBe('function');
+  });
+
+  /**
+   * @source docs/api/core.md#accessing-services-outside-of-requests
+   */
+  it('should get service instance by class', async () => {
+    @Service()
+    class TaskService extends BaseService {
+      performTask(): string {
+        return 'task completed';
+      }
+    }
+
+    @Module({
+      providers: [TaskService],
+      controllers: [],
+    })
+    class AppModule {}
+
+    const app = new OneBunApplication(AppModule, {
+      loggerLayer: makeMockLoggerLayer(),
+    });
+
+    await app.start();
+
+    // From docs: getService usage example
+    const taskService = app.getService(TaskService);
+    expect(taskService).toBeDefined();
+    expect(taskService.performTask()).toBe('task completed');
+
+    await app.stop();
+  });
+
+  /**
+   * @source docs/api/core.md#accessing-services-outside-of-requests
+   */
+  it('should throw error for non-existent service', async () => {
+    @Service()
+    class NonExistentService extends BaseService {}
+
+    @Module({
+      controllers: [],
+    })
+    class AppModule {}
+
+    const app = new OneBunApplication(AppModule, {
+      loggerLayer: makeMockLoggerLayer(),
+    });
+
+    await app.start();
+
+    // getService throws when service is not found
+    expect(() => app.getService(NonExistentService)).toThrow();
+
+    await app.stop();
+  });
+});
+
 describe('Validation API Documentation Examples', () => {
   describe('validate function (docs/api/validation.md)', () => {
     /**
@@ -2936,8 +3282,19 @@ import {
   createWsClient,
   matchPattern,
   makeMockLoggerLayer,
+  hasOnModuleInit,
+  hasOnApplicationInit,
+  hasOnModuleDestroy,
+  hasBeforeApplicationDestroy,
+  hasOnApplicationDestroy,
+  callOnModuleInit,
+  callOnApplicationInit,
+  callOnModuleDestroy,
+  callBeforeApplicationDestroy,
+  callOnApplicationDestroy,
 } from './';
 
+
 describe('SSE (Server-Sent Events) API Documentation (docs/api/controllers.md)', () => {
   describe('SseEvent Type (docs/api/controllers.md)', () => {
     /**

package/src/index.ts

@@ -70,6 +70,23 @@ export {
   type IConfig,
   type OneBunAppConfig,
   NotInitializedConfig,
+  // Lifecycle hooks interfaces
+  type OnModuleInit,
+  type OnApplicationInit,
+  type OnModuleDestroy,
+  type BeforeApplicationDestroy,
+  type OnApplicationDestroy,
+  // Lifecycle hooks helper functions
+  hasOnModuleInit,
+  hasOnApplicationInit,
+  hasOnModuleDestroy,
+  hasBeforeApplicationDestroy,
+  hasOnApplicationDestroy,
+  callOnModuleInit,
+  callOnApplicationInit,
+  callOnModuleDestroy,
+  callBeforeApplicationDestroy,
+  callOnApplicationDestroy,
 } from './module';
 
 // Application

package/src/module/index.ts

@@ -11,3 +11,4 @@ export { Controller as BaseController } from './controller';
 export * from './service';
 export * from './config.service';
 export * from './config.interface';
+export * from './lifecycle';

package/src/module/lifecycle.ts

@@ -0,0 +1,197 @@
+/**
+ * Lifecycle hooks interfaces for services and controllers.
+ * Implement these interfaces to hook into the application lifecycle.
+ *
+ * @example
+ * ```typescript
+ * import { Service, BaseService, OnModuleInit, OnModuleDestroy } from '@onebun/core';
+ *
+ * @Service()
+ * export class DatabaseService extends BaseService implements OnModuleInit, OnModuleDestroy {
+ *   async onModuleInit() {
+ *     await this.pool.connect();
+ *     this.logger.info('Database connected');
+ *   }
+ *
+ *   async onModuleDestroy() {
+ *     await this.pool.end();
+ *     this.logger.info('Database disconnected');
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Interface for hook called after module initialization.
+ * Called after the service/controller is instantiated and dependencies are injected.
+ */
+export interface OnModuleInit {
+  /**
+   * Called after the module has been initialized.
+   * Can be async - the framework will await completion.
+   */
+  onModuleInit(): Promise<void> | void;
+}
+
+/**
+ * Interface for hook called after application initialization.
+ * Called after all modules are initialized and before the HTTP server starts.
+ */
+export interface OnApplicationInit {
+  /**
+   * Called after the application has been initialized.
+   * Can be async - the framework will await completion.
+   */
+  onApplicationInit(): Promise<void> | void;
+}
+
+/**
+ * Interface for hook called when module is being destroyed.
+ * Called during application shutdown, after HTTP server stops.
+ */
+export interface OnModuleDestroy {
+  /**
+   * Called when the module is being destroyed.
+   * Can be async - the framework will await completion.
+   */
+  onModuleDestroy(): Promise<void> | void;
+}
+
+/**
+ * Interface for hook called before application shutdown begins.
+ * Called at the very start of the shutdown process.
+ */
+export interface BeforeApplicationDestroy {
+  /**
+   * Called before the application shutdown process begins.
+   * Can be async - the framework will await completion.
+   * @param signal - The signal that triggered the shutdown (e.g., 'SIGTERM', 'SIGINT')
+   */
+  beforeApplicationDestroy(signal?: string): Promise<void> | void;
+}
+
+/**
+ * Interface for hook called after application shutdown completes.
+ * Called at the very end of the shutdown process.
+ */
+export interface OnApplicationDestroy {
+  /**
+   * Called after the application shutdown process completes.
+   * Can be async - the framework will await completion.
+   * @param signal - The signal that triggered the shutdown (e.g., 'SIGTERM', 'SIGINT')
+   */
+  onApplicationDestroy(signal?: string): Promise<void> | void;
+}
+
+// =============================================================================
+// Helper functions for checking if an object implements lifecycle hooks
+// =============================================================================
+
+/**
+ * Check if an object has an onModuleInit method
+ */
+export function hasOnModuleInit(obj: unknown): obj is OnModuleInit {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    'onModuleInit' in obj &&
+    typeof (obj as OnModuleInit).onModuleInit === 'function'
+  );
+}
+
+/**
+ * Check if an object has an onApplicationInit method
+ */
+export function hasOnApplicationInit(obj: unknown): obj is OnApplicationInit {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    'onApplicationInit' in obj &&
+    typeof (obj as OnApplicationInit).onApplicationInit === 'function'
+  );
+}
+
+/**
+ * Check if an object has an onModuleDestroy method
+ */
+export function hasOnModuleDestroy(obj: unknown): obj is OnModuleDestroy {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    'onModuleDestroy' in obj &&
+    typeof (obj as OnModuleDestroy).onModuleDestroy === 'function'
+  );
+}
+
+/**
+ * Check if an object has a beforeApplicationDestroy method
+ */
+export function hasBeforeApplicationDestroy(obj: unknown): obj is BeforeApplicationDestroy {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    'beforeApplicationDestroy' in obj &&
+    typeof (obj as BeforeApplicationDestroy).beforeApplicationDestroy === 'function'
+  );
+}
+
+/**
+ * Check if an object has an onApplicationDestroy method
+ */
+export function hasOnApplicationDestroy(obj: unknown): obj is OnApplicationDestroy {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    'onApplicationDestroy' in obj &&
+    typeof (obj as OnApplicationDestroy).onApplicationDestroy === 'function'
+  );
+}
+
+// =============================================================================
+// Helper functions to call lifecycle hooks safely
+// =============================================================================
+
+/**
+ * Call onModuleInit on an object if it implements the hook
+ */
+export async function callOnModuleInit(obj: unknown): Promise<void> {
+  if (hasOnModuleInit(obj)) {
+    await obj.onModuleInit();
+  }
+}
+
+/**
+ * Call onApplicationInit on an object if it implements the hook
+ */
+export async function callOnApplicationInit(obj: unknown): Promise<void> {
+  if (hasOnApplicationInit(obj)) {
+    await obj.onApplicationInit();
+  }
+}
+
+/**
+ * Call onModuleDestroy on an object if it implements the hook
+ */
+export async function callOnModuleDestroy(obj: unknown): Promise<void> {
+  if (hasOnModuleDestroy(obj)) {
+    await obj.onModuleDestroy();
+  }
+}
+
+/**
+ * Call beforeApplicationDestroy on an object if it implements the hook
+ */
+export async function callBeforeApplicationDestroy(obj: unknown, signal?: string): Promise<void> {
+  if (hasBeforeApplicationDestroy(obj)) {
+    await obj.beforeApplicationDestroy(signal);
+  }
+}
+
+/**
+ * Call onApplicationDestroy on an object if it implements the hook
+ */
+export async function callOnApplicationDestroy(obj: unknown, signal?: string): Promise<void> {
+  if (hasOnApplicationDestroy(obj)) {
+    await obj.onApplicationDestroy(signal);
+  }
+}

package/src/module/module.ts

@@ -29,6 +29,13 @@ import {
   type IConfig,
   type OneBunAppConfig,
 } from './config.interface';
+import {
+  hasOnModuleInit,
+  hasOnApplicationInit,
+  hasOnModuleDestroy,
+  hasBeforeApplicationDestroy,
+  hasOnApplicationDestroy,
+} from './lifecycle';
 import { getServiceMetadata, getServiceTag } from './service';
 
 /**
@@ -68,7 +75,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 pendingServiceInits: Array<{ name: string; instance: unknown }> = [];
   private logger: SyncLogger;
   private config: IConfig<OneBunAppConfig>;
 
@@ -303,16 +310,11 @@ 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({
+        // Track services that need lifecycle hooks (onModuleInit)
+        if (hasOnModuleInit(serviceInstance)) {
+          this.pendingServiceInits.push({
             name: provider.name,
-            init: () => (serviceInstance as { onAsyncInit: () => Promise<void> }).onAsyncInit(),
+            instance: serviceInstance,
           });
         }
 
@@ -558,35 +560,45 @@ export class OneBunModule implements ModuleInstance {
    * Setup the module and its dependencies
    */
   setup(): Effect.Effect<unknown, never, void> {
-    return this.runAsyncServiceInit().pipe(
-      // Also run async init for child modules
+    return this.callServicesOnModuleInit().pipe(
+      // Also run onModuleInit for child modules' services
       Effect.flatMap(() =>
-        Effect.forEach(this.childModules, (childModule) => childModule.runAsyncServiceInit(), {
+        Effect.forEach(this.childModules, (childModule) => childModule.callServicesOnModuleInit(), {
           discard: true,
         }),
       ),
       // Then create controller instances
       Effect.flatMap(() => this.createControllerInstances()),
+      // Then call onModuleInit for controllers
+      Effect.flatMap(() => this.callControllersOnModuleInit()),
+      // Also run onModuleInit for child modules' controllers
+      Effect.flatMap(() =>
+        Effect.forEach(this.childModules, (childModule) => childModule.callControllersOnModuleInit(), {
+          discard: true,
+        }),
+      ),
     );
   }
 
   /**
-   * Run async initialization for all services that need it
+   * Call onModuleInit lifecycle hook for all services that implement it
    */
-  runAsyncServiceInit(): Effect.Effect<unknown, never, void> {
-    if (this.pendingAsyncInits.length === 0) {
+  callServicesOnModuleInit(): Effect.Effect<unknown, never, void> {
+    if (this.pendingServiceInits.length === 0) {
       return Effect.void;
     }
 
-    this.logger.debug(`Running async initialization for ${this.pendingAsyncInits.length} service(s)`);
+    this.logger.debug(`Calling onModuleInit for ${this.pendingServiceInits.length} service(s)`);
 
-    // Run all async inits in parallel
-    const initPromises = this.pendingAsyncInits.map(async ({ name, init }) => {
+    // Run all service onModuleInit hooks sequentially
+    const initPromises = this.pendingServiceInits.map(async ({ name, instance }) => {
       try {
-        await init();
-        this.logger.debug(`Service ${name} async initialization completed`);
+        if (hasOnModuleInit(instance)) {
+          await instance.onModuleInit();
+        }
+        this.logger.debug(`Service ${name} onModuleInit completed`);
       } catch (error) {
-        this.logger.error(`Service ${name} async initialization failed: ${error}`);
+        this.logger.error(`Service ${name} onModuleInit failed: ${error}`);
         throw error;
       }
     });
@@ -594,11 +606,179 @@ export class OneBunModule implements ModuleInstance {
     return Effect.promise(() => Promise.all(initPromises)).pipe(
       Effect.map(() => {
         // Clear the list after initialization
-        this.pendingAsyncInits = [];
+        this.pendingServiceInits = [];
       }),
     );
   }
 
+  /**
+   * Call onModuleInit lifecycle hook for all controllers that implement it
+   */
+  callControllersOnModuleInit(): Effect.Effect<unknown, never, void> {
+    const controllers = Array.from(this.controllerInstances.values());
+    const controllersWithInit = controllers.filter((c): c is Controller & { onModuleInit(): Promise<void> | void } => 
+      hasOnModuleInit(c),
+    );
+
+    if (controllersWithInit.length === 0) {
+      return Effect.void;
+    }
+
+    this.logger.debug(`Calling onModuleInit for ${controllersWithInit.length} controller(s)`);
+
+    const initPromises = controllersWithInit.map(async (controller) => {
+      try {
+        await controller.onModuleInit();
+        this.logger.debug(`Controller ${controller.constructor.name} onModuleInit completed`);
+      } catch (error) {
+        this.logger.error(`Controller ${controller.constructor.name} onModuleInit failed: ${error}`);
+        throw error;
+      }
+    });
+
+    return Effect.promise(() => Promise.all(initPromises));
+  }
+
+  /**
+   * Call onApplicationInit lifecycle hook for all services and controllers
+   */
+  async callOnApplicationInit(): Promise<void> {
+    // Call for services
+    for (const [, instance] of this.serviceInstances) {
+      if (hasOnApplicationInit(instance)) {
+        try {
+          await instance.onApplicationInit();
+          this.logger.debug(`Service ${(instance as object).constructor.name} onApplicationInit completed`);
+        } catch (error) {
+          this.logger.error(`Service ${(instance as object).constructor.name} onApplicationInit failed: ${error}`);
+          throw error;
+        }
+      }
+    }
+
+    // Call for controllers
+    for (const [, controller] of this.controllerInstances) {
+      if (hasOnApplicationInit(controller)) {
+        try {
+          await controller.onApplicationInit();
+          this.logger.debug(`Controller ${controller.constructor.name} onApplicationInit completed`);
+        } catch (error) {
+          this.logger.error(`Controller ${controller.constructor.name} onApplicationInit failed: ${error}`);
+          throw error;
+        }
+      }
+    }
+
+    // Call for child modules
+    for (const childModule of this.childModules) {
+      await childModule.callOnApplicationInit();
+    }
+  }
+
+  /**
+   * Call beforeApplicationDestroy lifecycle hook for all services and controllers
+   */
+  async callBeforeApplicationDestroy(signal?: string): Promise<void> {
+    // Call for services
+    for (const [, instance] of this.serviceInstances) {
+      if (hasBeforeApplicationDestroy(instance)) {
+        try {
+          await instance.beforeApplicationDestroy(signal);
+          this.logger.debug(`Service ${(instance as object).constructor.name} beforeApplicationDestroy completed`);
+        } catch (error) {
+          this.logger.error(`Service ${(instance as object).constructor.name} beforeApplicationDestroy failed: ${error}`);
+        }
+      }
+    }
+
+    // Call for controllers
+    for (const [, controller] of this.controllerInstances) {
+      if (hasBeforeApplicationDestroy(controller)) {
+        try {
+          await controller.beforeApplicationDestroy(signal);
+          this.logger.debug(`Controller ${controller.constructor.name} beforeApplicationDestroy completed`);
+        } catch (error) {
+          this.logger.error(`Controller ${controller.constructor.name} beforeApplicationDestroy failed: ${error}`);
+        }
+      }
+    }
+
+    // Call for child modules
+    for (const childModule of this.childModules) {
+      await childModule.callBeforeApplicationDestroy(signal);
+    }
+  }
+
+  /**
+   * Call onModuleDestroy lifecycle hook for controllers first, then services
+   */
+  async callOnModuleDestroy(): Promise<void> {
+    // Call for controllers first (reverse order of creation)
+    const controllers = Array.from(this.controllerInstances.values()).reverse();
+    for (const controller of controllers) {
+      if (hasOnModuleDestroy(controller)) {
+        try {
+          await controller.onModuleDestroy();
+          this.logger.debug(`Controller ${controller.constructor.name} onModuleDestroy completed`);
+        } catch (error) {
+          this.logger.error(`Controller ${controller.constructor.name} onModuleDestroy failed: ${error}`);
+        }
+      }
+    }
+
+    // Call for services (reverse order of creation)
+    const services = Array.from(this.serviceInstances.values()).reverse();
+    for (const instance of services) {
+      if (hasOnModuleDestroy(instance)) {
+        try {
+          await instance.onModuleDestroy();
+          this.logger.debug(`Service ${(instance as object).constructor.name} onModuleDestroy completed`);
+        } catch (error) {
+          this.logger.error(`Service ${(instance as object).constructor.name} onModuleDestroy failed: ${error}`);
+        }
+      }
+    }
+
+    // Call for child modules
+    for (const childModule of this.childModules) {
+      await childModule.callOnModuleDestroy();
+    }
+  }
+
+  /**
+   * Call onApplicationDestroy lifecycle hook for all services and controllers
+   */
+  async callOnApplicationDestroy(signal?: string): Promise<void> {
+    // Call for services
+    for (const [, instance] of this.serviceInstances) {
+      if (hasOnApplicationDestroy(instance)) {
+        try {
+          await instance.onApplicationDestroy(signal);
+          this.logger.debug(`Service ${(instance as object).constructor.name} onApplicationDestroy completed`);
+        } catch (error) {
+          this.logger.error(`Service ${(instance as object).constructor.name} onApplicationDestroy failed: ${error}`);
+        }
+      }
+    }
+
+    // Call for controllers
+    for (const [, controller] of this.controllerInstances) {
+      if (hasOnApplicationDestroy(controller)) {
+        try {
+          await controller.onApplicationDestroy(signal);
+          this.logger.debug(`Controller ${controller.constructor.name} onApplicationDestroy completed`);
+        } catch (error) {
+          this.logger.error(`Controller ${controller.constructor.name} onApplicationDestroy failed: ${error}`);
+        }
+      }
+    }
+
+    // Call for child modules
+    for (const childModule of this.childModules) {
+      await childModule.callOnApplicationDestroy(signal);
+    }
+  }
+
   /**
    * Get all controllers from this module
    */
@@ -627,12 +807,33 @@ export class OneBunModule implements ModuleInstance {
   }
 
   /**
-   * Get service instance
+   * Get service instance by tag
    */
   getServiceInstance<T>(tag: Context.Tag<T, T>): T | undefined {
     return this.serviceInstances.get(tag as Context.Tag<unknown, unknown>) as T | undefined;
   }
 
+  /**
+   * Get service instance by class
+   */
+  getServiceByClass<T>(serviceClass: new (...args: unknown[]) => T): T | undefined {
+    try {
+      const tag = getServiceTag(serviceClass);
+
+      return this.getServiceInstance(tag);
+    } catch {
+      // Service doesn't have @Service decorator or not found
+      return undefined;
+    }
+  }
+
+  /**
+   * Get all service instances
+   */
+  getAllServiceInstances(): Map<Context.Tag<unknown, unknown>, unknown> {
+    return new Map(this.serviceInstances);
+  }
+
   /**
    * Get the Layer for this module
    */

package/src/module/service.ts

@@ -99,16 +99,6 @@ 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

package/src/types.ts

@@ -1,7 +1,7 @@
 import type { Type } from 'arktype';
 import type { Effect, Layer } from 'effect';
 
-import type { Logger } from '@onebun/logger';
+import type { Logger, LoggerOptions } from '@onebun/logger';
 
 /**
  * Base interface for all OneBun services
@@ -58,6 +58,31 @@ export interface ModuleInstance {
    * Get controller instance
    */
   getControllerInstance?(controllerClass: Function): unknown;
+
+  /**
+   * Call onApplicationInit lifecycle hook for all services and controllers
+   */
+  callOnApplicationInit?(): Promise<void>;
+
+  /**
+   * Call beforeApplicationDestroy lifecycle hook for all services and controllers
+   */
+  callBeforeApplicationDestroy?(signal?: string): Promise<void>;
+
+  /**
+   * Call onModuleDestroy lifecycle hook for controllers first, then services
+   */
+  callOnModuleDestroy?(): Promise<void>;
+
+  /**
+   * Call onApplicationDestroy lifecycle hook for all services and controllers
+   */
+  callOnApplicationDestroy?(signal?: string): Promise<void>;
+
+  /**
+   * Get service instance by class
+   */
+  getServiceByClass?<T>(serviceClass: new (...args: unknown[]) => T): T | undefined;
 }
 
 /**
@@ -107,8 +132,28 @@ export interface ApplicationOptions {
   development?: boolean;
 
   /**
-   * Logger layer to use
-   * If not provided, a default logger will be created
+   * Logger configuration options.
+   * Provides a declarative way to configure logging.
+   * 
+   * Priority: loggerLayer > loggerOptions > LOG_LEVEL/LOG_FORMAT env > NODE_ENV defaults
+   * 
+   * @example
+   * ```typescript
+   * const app = new OneBunApplication(AppModule, {
+   *   loggerOptions: {
+   *     minLevel: 'info',
+   *     format: 'json',
+   *     defaultContext: { service: 'user-service' },
+   *   },
+   * });
+   * ```
+   */
+  loggerOptions?: LoggerOptions;
+
+  /**
+   * Logger layer to use (advanced).
+   * If provided, takes precedence over loggerOptions.
+   * Use loggerOptions for simpler configuration.
    */
   loggerLayer?: Layer.Layer<Logger>;