@onebun/core 0.1.18 → 0.1.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onebun/core",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "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.7",
     "@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)', () => {
     /**
@@ -1981,6 +2327,49 @@ describe('Architecture Documentation (docs/architecture.md)', () => {
       expect(SharedModule).toBeDefined();
       expect(ApiModule).toBeDefined();
     });
+
+    /**
+     * Exports are only required for cross-module injection.
+     * Within a module, any provider can be injected into controllers without being in exports.
+     */
+    it('should allow controller to inject same-module provider without exports', async () => {
+      const effectLib = await import('effect');
+      const moduleMod = await import('./module/module');
+      const testUtils = await import('./testing/test-utils');
+      const decorators = await import('./decorators/decorators');
+
+      @Service()
+      class InternalService extends BaseService {
+        getData(): string {
+          return 'internal';
+        }
+      }
+
+      @Controller('/local')
+      class LocalController extends BaseController {
+        constructor(@decorators.Inject(InternalService) private readonly internal: InternalService) {
+          super();
+        }
+        getData(): string {
+          return this.internal.getData();
+        }
+      }
+
+      @Module({
+        providers: [InternalService],
+        controllers: [LocalController],
+        // No exports - InternalService is only used inside this module
+      })
+      class LocalModule {}
+
+      const mod = new moduleMod.OneBunModule(LocalModule, testUtils.makeMockLoggerLayer());
+      mod.getLayer();
+      await effectLib.Effect.runPromise(mod.setup() as import('effect').Effect.Effect<unknown, never, never>);
+
+      const controller = mod.getControllerInstance(LocalController) as LocalController;
+      expect(controller).toBeDefined();
+      expect(controller.getData()).toBe('internal');
+    });
   });
 });
 
@@ -2936,8 +3325,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';