@onebun/core 0.1.18 → 0.1.20

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.test.ts

@@ -10,7 +10,11 @@ import {
   afterEach,
   mock,
 } from 'bun:test';
-import { Context } from 'effect';
+import {
+  Context,
+  Effect,
+  Layer,
+} from 'effect';
 
 import { Module } from '../decorators/decorators';
 import { makeMockLoggerLayer } from '../testing/test-utils';
@@ -157,7 +161,6 @@ describe('OneBunModule', () => {
 
     test('should detect circular dependencies and provide detailed error message', () => {
       const { registerDependencies } = require('../decorators/decorators');
-      const { Effect, Layer } = require('effect');
       const { LoggerService } = require('@onebun/logger');
 
       // Collect error messages
@@ -849,4 +852,145 @@ describe('OneBunModule', () => {
       expect((apiService as ApiService).getConnectionTimeout()).toBe(5000);
     });
   });
+
+  describe('Module DI scoping (exports only for cross-module)', () => {
+    const {
+      Controller: ControllerDecorator,
+      Get,
+      Inject,
+      clearGlobalModules,
+    } = require('../decorators/decorators');
+    const { Controller: BaseController } = require('./controller');
+    const { clearGlobalServicesRegistry: clearRegistry, OneBunModule: ModuleClass } = require('./module');
+
+    beforeEach(() => {
+      clearGlobalModules();
+      clearRegistry();
+    });
+
+    afterEach(() => {
+      clearGlobalModules();
+      clearRegistry();
+    });
+
+    test('controller can inject provider from same module without exports', async () => {
+      @Service()
+      class CounterService {
+        private count = 0;
+        getCount() {
+          return this.count;
+        }
+        increment() {
+          this.count += 1;
+        }
+      }
+
+      class CounterController extends BaseController {
+        constructor(@Inject(CounterService) private readonly counterService: CounterService) {
+          super();
+        }
+        getCount() {
+          return this.counterService.getCount();
+        }
+      }
+      const CounterControllerDecorated = ControllerDecorator('/counter')(CounterController);
+      Get('/')(CounterControllerDecorated.prototype, 'getCount', Object.getOwnPropertyDescriptor(CounterControllerDecorated.prototype, 'getCount')!);
+
+      @Module({
+        providers: [CounterService],
+        controllers: [CounterControllerDecorated],
+        // No exports - CounterService is only used inside this module
+      })
+      class FeatureModule {}
+
+      const module = new ModuleClass(FeatureModule, mockLoggerLayer);
+      module.getLayer();
+      await Effect.runPromise(module.setup() as Effect.Effect<unknown, never, never>);
+
+      const controller = module.getControllerInstance(CounterControllerDecorated) as CounterController;
+      expect(controller).toBeDefined();
+      expect(controller.getCount()).toBe(0);
+    });
+
+    test('child module controller injects own provider; root can resolve controller', async () => {
+      @Service()
+      class ChildService {
+        getValue() {
+          return 'child';
+        }
+      }
+
+      class ChildController extends BaseController {
+        constructor(@Inject(ChildService) private readonly childService: ChildService) {
+          super();
+        }
+        getValue() {
+          return this.childService.getValue();
+        }
+      }
+      const ChildControllerDecorated = ControllerDecorator('/child')(ChildController);
+      Get('/')(ChildControllerDecorated.prototype, 'getValue', Object.getOwnPropertyDescriptor(ChildControllerDecorated.prototype, 'getValue')!);
+
+      @Module({
+        providers: [ChildService],
+        controllers: [ChildControllerDecorated],
+      })
+      class ChildModule {}
+
+      @Module({
+        imports: [ChildModule],
+      })
+      class RootModule {}
+
+      const rootModule = new ModuleClass(RootModule, mockLoggerLayer);
+      rootModule.getLayer();
+      await Effect.runPromise(rootModule.setup() as Effect.Effect<unknown, never, never>);
+
+      const allControllers = rootModule.getControllers();
+      expect(allControllers).toContain(ChildControllerDecorated);
+      const controller = rootModule.getControllerInstance(ChildControllerDecorated) as ChildController;
+      expect(controller).toBeDefined();
+      expect(controller.getValue()).toBe('child');
+    });
+
+    test('exported service from imported module is injectable in importing module', async () => {
+      @Service()
+      class SharedService {
+        getLabel() {
+          return 'shared';
+        }
+      }
+
+      @Module({
+        providers: [SharedService],
+        exports: [SharedService],
+      })
+      class SharedModule {}
+
+      class AppController extends BaseController {
+        constructor(@Inject(SharedService) private readonly sharedService: SharedService) {
+          super();
+        }
+        getLabel() {
+          return this.sharedService.getLabel();
+        }
+      }
+      const AppControllerDecorated = ControllerDecorator('/app')(AppController);
+      Get('/')(AppControllerDecorated.prototype, 'getLabel', Object.getOwnPropertyDescriptor(AppControllerDecorated.prototype, 'getLabel')!);
+
+      @Module({
+        imports: [SharedModule],
+        controllers: [AppControllerDecorated],
+      })
+      class AppModule {}
+
+      const module = new ModuleClass(AppModule, mockLoggerLayer);
+      module.getLayer();
+      await Effect.runPromise(module.setup() as Effect.Effect<unknown, never, never>);
+
+      const controller = module.getControllerInstance(AppControllerDecorated) as AppController;
+      expect(controller).toBeDefined();
+      expect(controller.getLabel()).toBe('shared');
+    });
+  });
 });