@onebun/core 0.1.10 → 0.1.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onebun/core",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "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.test.ts

@@ -164,6 +164,98 @@ describe('OneBunApplication', () => {
       // The actual value access might need the config to be fully initialized
       // which happens during runtime, not during construction
     });
+
+    test('should provide typed access to config values via getConfig()', () => {
+      @Module({})
+      class TestModule {}
+
+      // Mock config that simulates typed IConfig<OneBunAppConfig>
+      const mockConfigValues = {
+        server: { port: 9991, host: 'localhost' },
+      };
+      const mockConfig = {
+        // eslint-disable-next-line @typescript-eslint/no-empty-function
+        initialize: mock(async () => {}),
+        get: mock((path: string) => {
+          const parts = path.split('.');
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          let value: any = mockConfigValues;
+          for (const part of parts) {
+            value = value?.[part];
+          }
+
+          return value;
+        }),
+        values: mockConfigValues,
+        getSafeConfig: mock(() => mockConfigValues),
+        isInitialized: true,
+      };
+
+      const app = createTestApp(TestModule);
+      // Inject mock config
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (app as any).config = mockConfig;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (app as any).configService = {
+        get: mockConfig.get, values: mockConfig.values, getSafeConfig: mockConfig.getSafeConfig, isInitialized: true, 
+      };
+
+      // getConfig() returns IConfig<OneBunAppConfig> which provides typed .get() method
+      const config = app.getConfig();
+      expect(config).toBeDefined();
+      
+      // Access values through the typed interface
+      // TypeScript will infer the correct types based on module augmentation
+      const port = config.get('server.port');
+      const host = config.get('server.host');
+      
+      expect(port).toBe(9991);
+      expect(host).toBe('localhost');
+    });
+
+    test('should provide typed access via getConfigValue() convenience method', () => {
+      @Module({})
+      class TestModule {}
+
+      // Mock config that simulates typed IConfig<OneBunAppConfig>
+      const mockConfigValues = {
+        app: { name: 'test-app', debug: true },
+      };
+      const mockConfig = {
+        // eslint-disable-next-line @typescript-eslint/no-empty-function
+        initialize: mock(async () => {}),
+        get: mock((path: string) => {
+          const parts = path.split('.');
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          let value: any = mockConfigValues;
+          for (const part of parts) {
+            value = value?.[part];
+          }
+
+          return value;
+        }),
+        values: mockConfigValues,
+        getSafeConfig: mock(() => mockConfigValues),
+        isInitialized: true,
+      };
+
+      const app = createTestApp(TestModule);
+      // Inject mock config
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (app as any).config = mockConfig;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (app as any).configService = {
+        get: mockConfig.get, values: mockConfig.values, getSafeConfig: mockConfig.getSafeConfig, isInitialized: true, 
+      };
+
+      // getConfigValue() is a convenience method that delegates to getConfig().get()
+      // It also provides typed access based on OneBunAppConfig module augmentation
+      const appName = app.getConfigValue('app.name');
+      const debug = app.getConfigValue('app.debug');
+      
+      expect(appName).toBe('test-app');
+      expect(debug).toBe(true);
+    });
   });
 
   describe('Layer methods', () => {

package/src/application/application.ts

@@ -3,7 +3,11 @@ import { Effect, type Layer } from 'effect';
 import type { Controller } from '../module/controller';
 import type { WsClientData } from '../websocket/ws.types';
 
-import { TypedEnv } from '@onebun/envs';
+import {
+  type DeepPaths,
+  type DeepValue,
+  TypedEnv,
+} from '@onebun/envs';
 import {
   createSyncLogger,
   type Logger,
@@ -21,6 +25,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 +119,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 +143,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 +165,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);
     }
 
@@ -224,9 +234,21 @@ export class OneBunApplication {
   }
 
   /**
-   * Get configuration service
+   * Get configuration service with full type inference.
+   * Uses module augmentation of OneBunAppConfig for type-safe access.
+   * 
+   * @example
+   * // With module augmentation:
+   * declare module '@onebun/core' {
+   *   interface OneBunAppConfig {
+   *     server: { port: number; host: string };
+   *   }
+   * }
+   * 
+   * const config = app.getConfig();
+   * const port = config.get('server.port'); // number
    */
-  getConfig(): ConfigServiceImpl {
+  getConfig(): IConfig<OneBunAppConfig> {
     if (!this.configService) {
       throw new Error('Configuration not initialized. Provide envSchema in ApplicationOptions.');
     }
@@ -235,10 +257,25 @@ export class OneBunApplication {
   }
 
   /**
-   * Get configuration value by path (convenience method)
+   * Get configuration value by path (convenience method) with full type inference.
+   * Uses module augmentation of OneBunAppConfig for type-safe access.
+   * 
+   * @example
+   * // With module augmentation:
+   * declare module '@onebun/core' {
+   *   interface OneBunAppConfig {
+   *     server: { port: number; host: string };
+   *   }
+   * }
+   * 
+   * const port = app.getConfigValue('server.port'); // number
+   * const host = app.getConfigValue('server.host'); // string
    */
-  getConfigValue<T = unknown>(path: string): T {
-    return this.getConfig().get<T>(path);
+  getConfigValue<P extends DeepPaths<OneBunAppConfig>>(path: P): DeepValue<OneBunAppConfig, P>;
+  /** Fallback for dynamic paths */
+  getConfigValue<T = unknown>(path: string): T;
+  getConfigValue(path: string): unknown {
+    return this.getConfig().get(path);
   }
 
   /**
@@ -289,8 +326,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');
         
@@ -133,11 +141,12 @@ describe('ConfigService', () => {
         
         const result = service.values;
         
-        expect(result).toEqual({ test: 'value' });
+        // Use unknown cast because tests use mock data that doesn't match OneBunAppConfig augmentation
+        expect(result as unknown).toEqual({ test: 'value' });
       });
 
       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.',
@@ -151,12 +160,13 @@ describe('ConfigService', () => {
         
         const result = service.getSafeConfig();
         
-        expect(result).toEqual({ test: '***' });
+        // Use unknown cast because tests use mock data that doesn't match OneBunAppConfig augmentation
+        expect(result as unknown).toEqual({ test: '***' });
         expect(mockConfig.getSafeConfig).toHaveBeenCalled();
       });
 
       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 +182,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 +209,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 +226,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 +235,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 +248,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 +269,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 +285,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,19 +340,21 @@ describe('ConfigService', () => {
           api: { key: '***', timeout: 30000 },
         })),
         isInitialized: true,
-      };
+      } as unknown as IConfig<OneBunAppConfig>;
 
       const service = new ConfigServiceImpl(mockLogger, complexConfig);
 
       expect((service as any).get('database.host')).toBe('localhost');
       expect((service as any).get('database.port')).toBe(5432);
-      expect(service.values).toEqual({
+      // Use unknown cast because tests use mock data that doesn't match OneBunAppConfig augmentation
+      expect(service.values as unknown).toEqual({
         database: { host: 'localhost', port: 5432 },
         api: { key: 'secret', timeout: 30000 },
       });
       
       const safeConfig = service.getSafeConfig();
-      expect(safeConfig).toEqual({
+      // Use unknown cast because tests use mock data that doesn't match OneBunAppConfig augmentation
+      expect(safeConfig as unknown).toEqual({
         database: { host: 'localhost', port: 5432 },
         api: { key: '***', timeout: 30000 },
       });