@onebun/core 0.1.17 → 0.1.19

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);
+  }
+}