@onebun/core 0.1.10 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onebun/core",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Core package for OneBun framework - decorators, DI, modules, controllers",
   "license": "LGPL-3.0",
   "author": "RemRyahirev",
@@ -41,14 +41,15 @@
   "dependencies": {
     "effect": "^3.13.10",
     "arktype": "^2.0.0",
-    "@onebun/logger": "^0.1.4",
-    "@onebun/envs": "^0.1.3",
-    "@onebun/metrics": "^0.1.5",
+    "@onebun/logger": "^0.1.5",
+    "@onebun/envs": "^0.1.4",
+    "@onebun/metrics": "^0.1.6",
     "@onebun/requests": "^0.1.3",
-    "@onebun/trace": "^0.1.3"
+    "@onebun/trace": "^0.1.4"
   },
   "devDependencies": {
-    "bun-types": "1.2.2"
+    "bun-types": "1.2.2",
+    "testcontainers": "^11.7.1"
   },
   "engines": {
     "bun": "1.2.2"

package/src/application/application.ts

@@ -21,6 +21,11 @@ import {
 import { makeTraceService, TraceService } from '@onebun/trace';
 
 import { getControllerMetadata } from '../decorators/decorators';
+import {
+  NotInitializedConfig,
+  type IConfig,
+  type OneBunAppConfig,
+} from '../module/config.interface';
 import { ConfigServiceImpl } from '../module/config.service';
 import { OneBunModule } from '../module/module';
 import { QueueService, type QueueAdapter } from '../queue';
@@ -110,8 +115,7 @@ export class OneBunApplication {
     development: process.env.NODE_ENV !== 'production',
   };
   private logger: SyncLogger;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  private config: any = null;
+  private config: IConfig<OneBunAppConfig>;
   private configService: ConfigServiceImpl | null = null;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   private metricsService: any = null;
@@ -135,10 +139,12 @@ export class OneBunApplication {
       this.options = { ...this.options, ...options };
     }
 
-    // Initialize configuration if schema is provided
+    // Initialize configuration - TypedEnv if schema provided, otherwise NotInitializedConfig
     if (this.options.envSchema) {
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       this.config = TypedEnv.create(this.options.envSchema as any, this.options.envOptions);
+    } else {
+      this.config = new NotInitializedConfig();
     }
 
     // Use provided logger layer or create a default one
@@ -155,8 +161,8 @@ export class OneBunApplication {
     ) as Logger;
     this.logger = createSyncLogger(effectLogger);
 
-    // Create configuration service if config is available
-    if (this.config) {
+    // Create configuration service if config is initialized
+    if (this.config.isInitialized || !(this.config instanceof NotInitializedConfig)) {
       this.configService = new ConfigServiceImpl(this.logger, this.config);
     }
 
@@ -289,8 +295,8 @@ export class OneBunApplication {
    */
   async start(): Promise<void> {
     try {
-      // Initialize configuration if provided
-      if (this.config) {
+      // Initialize configuration if schema was provided
+      if (!(this.config instanceof NotInitializedConfig)) {
         await this.config.initialize();
         this.logger.info('Application configuration initialized');
       }

package/src/docs-examples.test.ts

@@ -80,6 +80,7 @@ import {
   createWsServiceDefinition,
   createWsClient,
   matchPattern,
+  makeMockLoggerLayer,
 } from './';
 
 /**
@@ -157,6 +158,7 @@ describe('Minimal Working Example (docs/index.md)', () => {
     const app = new OneBunApplication(AppModule, {
       port: 3000,
       envSchema,
+      loggerLayer: makeMockLoggerLayer(),
       metrics: { enabled: true },
       tracing: { enabled: true },
     });
@@ -1302,6 +1304,7 @@ describe('OneBunApplication (docs/api/core.md)', () => {
 
     // From docs: OneBunApplication constructor
     const app = new OneBunApplication(AppModule, {
+      loggerLayer: makeMockLoggerLayer(),
       port: 3000,
       basePath: '/api/v1',
     });
@@ -1330,6 +1333,7 @@ describe('OneBunApplication (docs/api/core.md)', () => {
       basePath: '/api/v1',
       routePrefix: 'myservice',
       development: true,
+      loggerLayer: makeMockLoggerLayer(),
       metrics: {
         enabled: true,
         path: '/metrics',
@@ -1369,7 +1373,7 @@ describe('OneBunApplication (docs/api/core.md)', () => {
       httpDurationBuckets: [0.01, 0.05, 0.1, 0.5, 1, 2, 5],
     };
 
-    const app = new OneBunApplication(AppModule, { metrics: metricsOptions });
+    const app = new OneBunApplication(AppModule, { metrics: metricsOptions, loggerLayer: makeMockLoggerLayer() });
     expect(app).toBeDefined();
   });
 
@@ -1400,7 +1404,7 @@ describe('OneBunApplication (docs/api/core.md)', () => {
     };
     /* eslint-enable @typescript-eslint/naming-convention */
 
-    const app = new OneBunApplication(AppModule, { tracing: tracingOptions });
+    const app = new OneBunApplication(AppModule, { tracing: tracingOptions, loggerLayer: makeMockLoggerLayer() });
     expect(app).toBeDefined();
   });
 });
@@ -2182,6 +2186,7 @@ describe('Getting Started Documentation (docs/getting-started.md)', () => {
           loadDotEnv: true,
           envFilePath: '.env',
         },
+        loggerLayer: makeMockLoggerLayer(),
         metrics: {
           enabled: true,
           path: '/metrics',
@@ -2589,6 +2594,7 @@ describe('WebSocket Gateway API Documentation (docs/api/websocket.md)', () => {
           pingTimeout: 20000,
           maxPayload: 1048576,
         },
+        loggerLayer: makeMockLoggerLayer(),
       });
 
       expect(app).toBeDefined();
@@ -2865,6 +2871,7 @@ describe('WebSocket Chat Example (docs/examples/websocket-chat.md)', () => {
           pingInterval: 25000,
           pingTimeout: 20000,
         },
+        loggerLayer: makeMockLoggerLayer(),
       });
 
       expect(app).toBeDefined();

package/src/index.ts

@@ -1,5 +1,11 @@
 // Re-export from external packages
-export { Env, type EnvSchema, EnvValidationError } from '@onebun/envs';
+export {
+  Env,
+  type EnvSchema,
+  EnvValidationError,
+  type InferConfigType,
+  type EnvVariableConfig,
+} from '@onebun/envs';
 export type { SyncLogger } from '@onebun/logger';
 export {
   createHttpClient,
@@ -56,6 +62,10 @@ export {
   // Global modules support
   clearGlobalServicesRegistry,
   getGlobalServicesRegistry,
+  // Config interface types
+  type IConfig,
+  type OneBunAppConfig,
+  NotInitializedConfig,
 } from './module';
 
 // Application

package/src/module/config.interface.ts

@@ -0,0 +1,60 @@
+import type { DeepPaths, DeepValue } from '@onebun/envs';
+
+/**
+ * Empty interface for module augmentation.
+ * Users extend this to provide typed config access.
+ * 
+ * @example
+ * declare module '@onebun/core' {
+ *   interface OneBunAppConfig {
+ *     server: { port: number; host: string };
+ *   }
+ * }
+ */
+ 
+export interface OneBunAppConfig {}
+
+/**
+ * Generic typed configuration interface.
+ * Provides type-safe access to configuration values.
+ */
+export interface IConfig<T = OneBunAppConfig> {
+  /** Get configuration value by dot-notation path with full type inference */
+  get<P extends DeepPaths<T>>(path: P): DeepValue<T, P>;
+  /** Fallback for dynamic paths */
+  get(path: string): unknown;
+  /** Get all configuration values */
+  readonly values: T;
+  /** Get safe configuration for logging (sensitive data masked) */
+  getSafeConfig(): T;
+  /** Check if configuration is initialized */
+  readonly isInitialized: boolean;
+  /** Initialize configuration (async) */
+  initialize(): Promise<void>;
+}
+
+/**
+ * Config stub that throws on any access.
+ * Used when envSchema is not provided.
+ */
+export class NotInitializedConfig implements IConfig<never> {
+  get(_path: string): never {
+    throw new Error('Configuration not initialized. Provide envSchema in ApplicationOptions.');
+  }
+  
+  get values(): never {
+    throw new Error('Configuration not initialized. Provide envSchema in ApplicationOptions.');
+  }
+  
+  getSafeConfig(): never {
+    throw new Error('Configuration not initialized. Provide envSchema in ApplicationOptions.');
+  }
+  
+  get isInitialized(): boolean {
+    return false;
+  }
+  
+  async initialize(): Promise<void> {
+    throw new Error('Configuration not initialized. Provide envSchema in ApplicationOptions.');
+  }
+}

package/src/module/config.service.test.ts

@@ -11,6 +11,8 @@ import {
   mock,
 } from 'bun:test';
 
+import type { IConfig, OneBunAppConfig } from './config.interface';
+
 import type { SyncLogger } from '@onebun/logger';
 
 import {
@@ -22,7 +24,7 @@ import {
 describe('ConfigService', () => {
   let mockLogger: SyncLogger;
    
-  let mockConfig: any;
+  let mockConfig: IConfig<OneBunAppConfig>;
 
   beforeEach(() => {
     mockLogger = {
@@ -38,8 +40,8 @@ describe('ConfigService', () => {
     mockConfig = {
       initialize: mock(async () => {}),
       get: mock((path: string): any => `value-for-${path}`),
-      values: { test: 'value' },
-      getSafeConfig: mock(() => ({ test: '***' })),
+      values: { test: 'value' } as unknown as OneBunAppConfig,
+      getSafeConfig: mock(() => ({ test: '***' })) as unknown as () => OneBunAppConfig,
       isInitialized: true,
     };
   });
@@ -63,7 +65,7 @@ describe('ConfigService', () => {
       const service = new ConfigServiceImpl(mockLogger);
       
       expect(service).toBeInstanceOf(ConfigServiceImpl);
-      expect(service.instance).toBeUndefined();
+      expect(service.instance).toBeNull();
     });
 
     test('should create instance with config but without logger (uninitialized)', () => {
@@ -83,8 +85,8 @@ describe('ConfigService', () => {
         expect(mockLogger.info).toHaveBeenCalledWith('Configuration initialized successfully');
       });
 
-      test('should not throw when config instance is null', async () => {
-        const service = new ConfigServiceImpl(mockLogger, null);
+      test('should not throw when config instance is undefined', async () => {
+        const service = new ConfigServiceImpl(mockLogger, undefined);
         
         await expect(service.initialize()).resolves.toBeUndefined();
         expect(mockLogger.info).not.toHaveBeenCalled();
@@ -109,7 +111,7 @@ describe('ConfigService', () => {
       });
 
       test('should throw error when config not initialized', () => {
-        const service = new ConfigServiceImpl(mockLogger, null);
+        const service = new ConfigServiceImpl(mockLogger, undefined);
         
         expect(() => service.get('test.path')).toThrow(
           'Configuration not initialized. Provide envSchema in ApplicationOptions.',
@@ -117,8 +119,14 @@ describe('ConfigService', () => {
       });
 
       test('should return typed value', () => {
-        mockConfig.get.mockReturnValue(42);
-        const service = new ConfigServiceImpl(mockLogger, mockConfig);
+        const typedConfig = {
+          initialize: mock(async () => {}),
+          get: mock((path: string) => path === 'test.number' ? 42 : undefined),
+          values: { test: 'value' } as unknown as OneBunAppConfig,
+          getSafeConfig: mock(() => ({ test: '***' })) as unknown as () => OneBunAppConfig,
+          isInitialized: true,
+        } as unknown as IConfig<OneBunAppConfig>;
+        const service = new ConfigServiceImpl(mockLogger, typedConfig);
         
         const result = service.get<number>('test.number');
         
@@ -137,7 +145,7 @@ describe('ConfigService', () => {
       });
 
       test('should throw error when config not initialized', () => {
-        const service = new ConfigServiceImpl(mockLogger, null);
+        const service = new ConfigServiceImpl(mockLogger, undefined);
         
         expect(() => service.values).toThrow(
           'Configuration not initialized. Provide envSchema in ApplicationOptions.',
@@ -156,7 +164,7 @@ describe('ConfigService', () => {
       });
 
       test('should throw error when config not initialized', () => {
-        const service = new ConfigServiceImpl(mockLogger, null);
+        const service = new ConfigServiceImpl(mockLogger, undefined);
         
         expect(() => service.getSafeConfig()).toThrow(
           'Configuration not initialized. Provide envSchema in ApplicationOptions.',
@@ -172,14 +180,20 @@ describe('ConfigService', () => {
       });
 
       test('should return false when config not initialized', () => {
-        mockConfig.isInitialized = false;
-        const service = new ConfigServiceImpl(mockLogger, mockConfig);
+        const uninitConfig = {
+          initialize: mock(async () => {}),
+          get: mock((path: string): any => `value-for-${path}`),
+          values: { test: 'value' } as unknown as OneBunAppConfig,
+          getSafeConfig: mock(() => ({ test: '***' })) as unknown as () => OneBunAppConfig,
+          isInitialized: false,
+        } as unknown as IConfig<OneBunAppConfig>;
+        const service = new ConfigServiceImpl(mockLogger, uninitConfig);
         
         expect(service.isInitialized).toBe(false);
       });
 
-      test('should return false when config instance is null', () => {
-        const service = new ConfigServiceImpl(mockLogger, null);
+      test('should return false when config instance is undefined', () => {
+        const service = new ConfigServiceImpl(mockLogger, undefined);
         
         expect(service.isInitialized).toBe(false);
       });
@@ -193,7 +207,7 @@ describe('ConfigService', () => {
       });
 
       test('should return null when no config provided', () => {
-        const service = new ConfigServiceImpl(mockLogger, null);
+        const service = new ConfigServiceImpl(mockLogger, undefined);
         
         expect(service.instance).toBeNull();
       });
@@ -210,7 +224,7 @@ describe('ConfigService', () => {
       test('should handle undefined config in constructor', () => {
         const service = new ConfigServiceImpl(mockLogger, undefined);
         
-        expect(service.instance).toBeUndefined();
+        expect(service.instance).toBeNull();
         expect(service.isInitialized).toBe(false);
       });
     });
@@ -219,8 +233,11 @@ describe('ConfigService', () => {
       test('should handle initialization error gracefully', async () => {
         const errorConfig = {
           initialize: mock(() => Promise.reject(new Error('Init failed'))),
+          get: mock(() => undefined),
+          values: {} as unknown as OneBunAppConfig,
+          getSafeConfig: mock(() => ({})) as unknown as () => OneBunAppConfig,
           isInitialized: false,
-        };
+        } as unknown as IConfig<OneBunAppConfig>;
         
         const service = new ConfigServiceImpl(mockLogger, errorConfig);
         
@@ -229,15 +246,16 @@ describe('ConfigService', () => {
 
       test('should handle config method errors', () => {
         const errorConfig = {
+          initialize: mock(async () => {}),
           get: mock(() => {
             throw new Error('Get failed'); 
           }),
-          values: null,
+          values: null as unknown as unknown as OneBunAppConfig,
           getSafeConfig: mock(() => {
             throw new Error('Safe config failed'); 
-          }),
+          }) as unknown as () => OneBunAppConfig,
           isInitialized: true,
-        };
+        } as unknown as IConfig<OneBunAppConfig>;
         
         const service = new ConfigServiceImpl(mockLogger, errorConfig);
         
@@ -249,11 +267,12 @@ describe('ConfigService', () => {
     describe('edge cases', () => {
       test('should handle config with null values', () => {
         const nullConfig = {
+          initialize: mock(async () => {}),
           get: mock(() => null),
-          values: null,
-          getSafeConfig: mock(() => null),
+          values: null as unknown as unknown as OneBunAppConfig,
+          getSafeConfig: mock(() => null as unknown as unknown as OneBunAppConfig),
           isInitialized: true,
-        };
+        } as unknown as IConfig<OneBunAppConfig>;
         
         const service = new ConfigServiceImpl(mockLogger, nullConfig);
         
@@ -264,11 +283,12 @@ describe('ConfigService', () => {
 
       test('should handle config with undefined values', () => {
         const undefinedConfig = {
+          initialize: mock(async () => {}),
           get: mock(() => undefined),
-          values: undefined,
-          getSafeConfig: mock(() => undefined),
+          values: undefined as unknown as unknown as OneBunAppConfig,
+          getSafeConfig: mock(() => undefined as unknown as unknown as OneBunAppConfig),
           isInitialized: false,
-        };
+        } as unknown as IConfig<OneBunAppConfig>;
         
         const service = new ConfigServiceImpl(mockLogger, undefinedConfig);
         
@@ -318,7 +338,7 @@ describe('ConfigService', () => {
           api: { key: '***', timeout: 30000 },
         })),
         isInitialized: true,
-      };
+      } as unknown as IConfig<OneBunAppConfig>;
 
       const service = new ConfigServiceImpl(mockLogger, complexConfig);
 

package/src/module/config.service.ts

@@ -1,5 +1,7 @@
 import { Context } from 'effect';
 
+import type { IConfig, OneBunAppConfig } from './config.interface';
+
 import type { SyncLogger } from '@onebun/logger';
 
 import { BaseService, Service } from './service';
@@ -15,17 +17,16 @@ export const ConfigServiceTag = Context.GenericTag<ConfigServiceImpl>('ConfigSer
  */
 @Service(ConfigServiceTag)
 export class ConfigServiceImpl extends BaseService {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  private configInstance: any = null;
+  private configInstance: IConfig<OneBunAppConfig> | null = null;
 
-  constructor(logger?: SyncLogger, config?: unknown) {
+  constructor(logger?: SyncLogger, config?: IConfig<OneBunAppConfig>) {
     super();
     // If logger is provided directly (for backwards compatibility in tests),
     // initialize the service immediately
-    if (logger) {
+    if (logger && config) {
       this.initializeService(logger, config);
     }
-    this.configInstance = config;
+    this.configInstance = config ?? null;
   }
 
   /**
@@ -46,7 +47,7 @@ export class ConfigServiceImpl extends BaseService {
       throw new Error('Configuration not initialized. Provide envSchema in ApplicationOptions.');
     }
 
-    return this.configInstance.get(path);
+    return this.configInstance.get(path) as T;
   }
 
   /**

package/src/module/controller.test.ts

@@ -12,13 +12,17 @@ import {
 } from 'bun:test';
 import { Context } from 'effect';
 
+import type { IConfig, OneBunAppConfig } from './config.interface';
+
 import type { SyncLogger } from '@onebun/logger';
 
+import { createMockConfig } from '../testing/test-utils';
+
 import { Controller } from './controller';
 
 describe('Controller', () => {
   let mockLogger: SyncLogger;
-  let mockConfig: unknown;
+  let mockConfig: IConfig<OneBunAppConfig>;
 
   beforeEach(() => {
     mockLogger = {
@@ -31,13 +35,11 @@ describe('Controller', () => {
       child: mock(() => mockLogger),
     };
 
-    mockConfig = {
-      test: 'value',
-      database: {
-        host: 'localhost',
-        port: 5432,
-      },
-    };
+    mockConfig = createMockConfig({
+      'test': 'value',
+      'database.host': 'localhost',
+      'database.port': 5432,
+    });
   });
 
   describe('Controller initialization', () => {
@@ -139,33 +141,28 @@ describe('Controller', () => {
       expect(mockLogger.debug).toHaveBeenCalledWith('Controller CustomNamedController initialized');
     });
 
-    test('should work with different config types', () => {
+    test('should provide typed config access', () => {
       class TestController extends Controller {
-        getConfigType() {
-          return typeof this.config;
+        getConfigValue(path: string) {
+          return this.config.get(path);
+        }
+        
+        checkConfigInitialized() {
+          return this.config.isInitialized;
         }
       }
 
       const controller = new TestController();
+      const typedConfig = createMockConfig({
+        'server.port': 3000,
+        'server.host': '0.0.0.0',
+      });
       
-      // Test with object config
-      controller.initializeController(mockLogger, { test: 'value' });
-      expect(controller.getConfigType()).toBe('object');
+      controller.initializeController(mockLogger, typedConfig);
       
-      // Test with string config
-      const controller2 = new TestController();
-      controller2.initializeController(mockLogger, 'string-config');
-      expect(controller2.getConfigType()).toBe('string');
-
-      // Test with null config
-      const controller3 = new TestController();
-      controller3.initializeController(mockLogger, null);
-      expect(controller3.getConfigType()).toBe('object'); // null is typeof 'object'
-
-      // Test with undefined config
-      const controller4 = new TestController();
-      controller4.initializeController(mockLogger, undefined);
-      expect(controller4.getConfigType()).toBe('undefined');
+      expect(controller.getConfigValue('server.port')).toBe(3000);
+      expect(controller.getConfigValue('server.host')).toBe('0.0.0.0');
+      expect(controller.checkConfigInitialized()).toBe(true);
     });
   });
 
@@ -252,7 +249,8 @@ describe('Controller', () => {
         debug: mock(() => {}),
       };
 
-      controller.initializeController(newMockLogger, { newConfig: true });
+      const newConfig = createMockConfig({ 'newConfig': true });
+      controller.initializeController(newMockLogger, newConfig);
       expect(newMockLogger.debug).toHaveBeenCalledWith('Controller TestController initialized');
     });
   });

package/src/module/controller.ts

@@ -1,3 +1,4 @@
+import type { IConfig, OneBunAppConfig } from './config.interface';
 import type { Context } from 'effect';
 
 import type { SyncLogger } from '@onebun/logger';
@@ -14,13 +15,13 @@ export class Controller {
   // Logger instance with controller class name as context
   protected logger!: SyncLogger;
   // Configuration instance for accessing environment variables
-  protected config!: unknown;
+  protected config!: IConfig<OneBunAppConfig>;
 
   /**
    * Initialize controller with logger and config (called by the framework)
    * @internal
    */
-  initializeController(logger: SyncLogger, config: unknown): void {
+  initializeController(logger: SyncLogger, config: IConfig<OneBunAppConfig>): void {
     const className = this.constructor.name;
 
     if (logger) {

package/src/module/index.ts

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