moved folders around

libs/core/config/README.md

@@ -0,0 +1,243 @@
+# @stock-bot/config
+
+A robust, type-safe configuration library for the Stock Bot application. Built with Zod for validation and supports multiple configuration sources with proper precedence.
+
+## Features
+
+- **Type-safe configuration** with Zod schemas
+- **Multiple configuration sources**: JSON files and environment variables
+- **Environment-specific overrides** (development, test, production)
+- **Dynamic provider configurations**
+- **No circular dependencies** - designed to be used by all other libraries
+- **Clear error messages** with validation
+- **Runtime configuration updates** (useful for testing)
+- **Singleton pattern** for global configuration access
+
+## Installation
+
+```bash
+bun add @stock-bot/config
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { initializeConfig, getConfig } from '@stock-bot/config';
+
+// Initialize configuration (call once at app startup)
+await initializeConfig();
+
+// Get configuration
+const config = getConfig();
+console.log(config.database.postgres.host);
+
+// Use convenience functions
+import { getDatabaseConfig, isProduction } from '@stock-bot/config';
+
+const dbConfig = getDatabaseConfig();
+if (isProduction()) {
+  // Production-specific logic
+}
+```
+
+### Custom Configuration
+
+```typescript
+import { ConfigManager } from '@stock-bot/config';
+import { z } from 'zod';
+
+// Define your schema
+const myConfigSchema = z.object({
+  app: z.object({
+    name: z.string(),
+    version: z.string(),
+  }),
+  features: z.object({
+    enableBeta: z.boolean().default(false),
+  }),
+});
+
+// Create config manager
+const configManager = new ConfigManager({
+  configPath: './my-config',
+});
+
+// Initialize with schema
+const config = await configManager.initialize(myConfigSchema);
+```
+
+### Provider-Specific Configuration
+
+```typescript
+import { getProviderConfig } from '@stock-bot/config';
+
+// Get provider configuration
+const eodConfig = getProviderConfig('eod');
+console.log(eodConfig.apiKey);
+
+// Check if provider is enabled
+if (eodConfig.enabled) {
+  // Use EOD provider
+}
+```
+
+### Environment Variables
+
+Environment variables are loaded with the `STOCKBOT_` prefix and follow a naming convention:
+
+```bash
+# Database configuration
+STOCKBOT_DATABASE_POSTGRES_HOST=localhost
+STOCKBOT_DATABASE_POSTGRES_PORT=5432
+
+# Provider configuration
+STOCKBOT_PROVIDERS_EOD_API_KEY=your_api_key
+STOCKBOT_PROVIDERS_EOD_ENABLED=true
+
+# Service configuration
+STOCKBOT_SERVICE_PORT=3000
+STOCKBOT_LOGGING_LEVEL=debug
+```
+
+### Configuration Precedence
+
+Configuration is loaded in the following order (later sources override earlier ones):
+
+1. `config/default.json` - Base configuration
+2. `config/{environment}.json` - Environment-specific overrides
+3. Environment variables - Highest priority
+
+### Advanced Usage
+
+```typescript
+import { getConfigManager } from '@stock-bot/config';
+
+const manager = getConfigManager();
+
+// Get specific value by path
+const port = manager.getValue<number>('service.port');
+
+// Check if configuration exists
+if (manager.has('providers.ib')) {
+  // IB provider is configured
+}
+
+// Update configuration at runtime (useful for testing)
+manager.set({
+  logging: {
+    level: 'debug'
+  }
+});
+
+// Create typed getter
+const getQueueConfig = manager.createTypedGetter(queueConfigSchema);
+const queueConfig = getQueueConfig();
+```
+
+## Configuration Schema
+
+The library provides pre-defined schemas for common configurations:
+
+### Base Configuration
+- `environment` - Current environment (development/test/production)
+- `name` - Application name
+- `version` - Application version
+- `debug` - Debug mode flag
+
+### Service Configuration
+- `name` - Service name
+- `port` - Service port
+- `host` - Service host
+- `healthCheckPath` - Health check endpoint
+- `cors` - CORS configuration
+
+### Database Configuration
+- `postgres` - PostgreSQL configuration
+- `questdb` - QuestDB configuration
+- `mongodb` - MongoDB configuration
+- `dragonfly` - Dragonfly/Redis configuration
+
+### Provider Configuration
+- `eod` - EOD Historical Data provider
+- `ib` - Interactive Brokers provider
+- `qm` - QuoteMedia provider
+- `yahoo` - Yahoo Finance provider
+
+## Testing
+
+```typescript
+import { resetConfig, initializeConfig } from '@stock-bot/config';
+
+beforeEach(() => {
+  resetConfig();
+});
+
+test('custom config', async () => {
+  process.env.NODE_ENV = 'test';
+  process.env.STOCKBOT_SERVICE_PORT = '4000';
+  
+  await initializeConfig();
+  const config = getConfig();
+  
+  expect(config.service.port).toBe(4000);
+});
+```
+
+## Custom Loaders
+
+You can create custom configuration loaders:
+
+```typescript
+import { ConfigLoader } from '@stock-bot/config';
+
+class ApiConfigLoader implements ConfigLoader {
+  readonly priority = 75; // Between file (50) and env (100)
+  
+  async load(): Promise<Record<string, unknown>> {
+    // Fetch configuration from API
+    const response = await fetch('https://api.example.com/config');
+    return response.json();
+  }
+}
+
+// Use custom loader
+const configManager = new ConfigManager({
+  loaders: [
+    new FileLoader('./config', 'production'),
+    new ApiConfigLoader(),
+    new EnvLoader('STOCKBOT_'),
+  ],
+});
+```
+
+## Error Handling
+
+The library provides specific error types:
+
+```typescript
+import { ConfigError, ConfigValidationError } from '@stock-bot/config';
+
+try {
+  await initializeConfig();
+} catch (error) {
+  if (error instanceof ConfigValidationError) {
+    console.error('Validation failed:', error.errors);
+  } else if (error instanceof ConfigError) {
+    console.error('Configuration error:', error.message);
+  }
+}
+```
+
+## Best Practices
+
+1. **Initialize once**: Call `initializeConfig()` once at application startup
+2. **Use schemas**: Always define and validate configurations with Zod schemas
+3. **Environment variables**: Use the `STOCKBOT_` prefix for all env vars
+4. **Type safety**: Leverage TypeScript types from the schemas
+5. **Testing**: Reset configuration between tests with `resetConfig()`
+
+## License
+
+MIT