@abdokouta/react-config 1.0.0 → 1.0.2

package/.examples/02-env-helper.ts

@@ -1,282 +0,0 @@
-/**
- * Env Helper Example
- * 
- * This example demonstrates the standalone Env utility for quick
- * environment variable access without dependency injection.
- * 
- * @example
- * Run this example:
- * ```bash
- * ts-node examples/02-env-helper.ts
- * ```
- */
-
-import { Env } from '@abdokouta/config';
-
-/**
- * Setup example environment variables
- */
-function setupEnv() {
-  process.env.APP_NAME = 'My Application';
-  process.env.APP_PORT = '3000';
-  process.env.APP_DEBUG = 'true';
-  process.env.NODE_ENV = 'development';
-  process.env.API_TIMEOUT = '5000';
-  process.env.ENABLE_CACHE = '1';
-  process.env.ALLOWED_ORIGINS = 'http://localhost:3000,http://localhost:4000';
-  process.env.FEATURE_FLAGS = JSON.stringify({
-    newUI: true,
-    betaFeatures: false,
-  });
-}
-
-/**
- * Example 1: Basic Env usage
- */
-function basicUsage() {
-  console.log('\n=== Example 1: Basic Env Usage ===\n');
-
-  // Get string values
-  const appName = Env.get('APP_NAME');
-  console.log(`✓ APP_NAME: "${appName}"`);
-
-  // Get with default
-  const appEnv = Env.get('APP_ENV', 'production');
-  console.log(`✓ APP_ENV: "${appEnv}" (using default)`);
-
-  // Get non-existent key
-  const apiKey = Env.get('API_KEY');
-  console.log(`✓ API_KEY: ${apiKey} (undefined)`);
-}
-
-/**
- * Example 2: Type-safe getters
- */
-function typeSafeGetters() {
-  console.log('\n=== Example 2: Type-Safe Getters ===\n');
-
-  // Get string
-  const appName = Env.getString('APP_NAME', 'Default App');
-  console.log(`✓ getString('APP_NAME'): "${appName}"`);
-
-  // Get number
-  const port = Env.getNumber('APP_PORT', 3000);
-  console.log(`✓ getNumber('APP_PORT'): ${port} (type: ${typeof port})`);
-
-  // Get boolean
-  const debug = Env.getBool('APP_DEBUG', false);
-  console.log(`✓ getBool('APP_DEBUG'): ${debug} (type: ${typeof debug})`);
-
-  // Get array
-  const origins = Env.getArray('ALLOWED_ORIGINS', []);
-  console.log(`✓ getArray('ALLOWED_ORIGINS'):`, origins);
-
-  // Get JSON
-  const features = Env.getJson('FEATURE_FLAGS', {});
-  console.log(`✓ getJson('FEATURE_FLAGS'):`, features);
-}
-
-/**
- * Example 3: Required values
- */
-function requiredValues() {
-  console.log('\n=== Example 3: Required Values ===\n');
-
-  try {
-    // Get required value that exists
-    const appName = Env.getOrThrow('APP_NAME');
-    console.log(`✓ getOrThrow('APP_NAME'): "${appName}"`);
-
-    // Try to get required value that doesn't exist
-    const apiKey = Env.getOrThrow('API_KEY');
-    console.log(`✓ getOrThrow('API_KEY'): "${apiKey}"`);
-  } catch (error) {
-    console.log(`✗ Error: ${(error as Error).message}`);
-  }
-}
-
-/**
- * Example 4: Check existence
- */
-function checkExistence() {
-  console.log('\n=== Example 4: Check Existence ===\n');
-
-  const hasAppName = Env.has('APP_NAME');
-  console.log(`✓ has('APP_NAME'): ${hasAppName}`);
-
-  const hasApiKey = Env.has('API_KEY');
-  console.log(`✓ has('API_KEY'): ${hasApiKey}`);
-}
-
-/**
- * Example 5: Get all environment variables
- */
-function getAllEnv() {
-  console.log('\n=== Example 5: Get All Environment Variables ===\n');
-
-  const allEnv = Env.all();
-  const appVars = Object.keys(allEnv).filter(k => k.startsWith('APP_'));
-  
-  console.log('✓ All APP_* environment variables:');
-  appVars.forEach(key => {
-    console.log(`  - ${key}: ${allEnv[key]}`);
-  });
-}
-
-/**
- * Example 6: Practical use case - Configuration class
- */
-class AppConfig {
-  static get name(): string {
-    return Env.getString('APP_NAME', 'My App');
-  }
-
-  static get port(): number {
-    return Env.getNumber('APP_PORT', 3000);
-  }
-
-  static get debug(): boolean {
-    return Env.getBool('APP_DEBUG', false);
-  }
-
-  static get environment(): string {
-    return Env.getString('NODE_ENV', 'development');
-  }
-
-  static get isProduction(): boolean {
-    return this.environment === 'production';
-  }
-
-  static get isDevelopment(): boolean {
-    return this.environment === 'development';
-  }
-
-  static get apiTimeout(): number {
-    return Env.getNumber('API_TIMEOUT', 5000);
-  }
-
-  static get allowedOrigins(): string[] {
-    return Env.getArray('ALLOWED_ORIGINS', ['http://localhost:3000']);
-  }
-
-  static toJSON() {
-    return {
-      name: this.name,
-      port: this.port,
-      debug: this.debug,
-      environment: this.environment,
-      isProduction: this.isProduction,
-      isDevelopment: this.isDevelopment,
-      apiTimeout: this.apiTimeout,
-      allowedOrigins: this.allowedOrigins,
-    };
-  }
-}
-
-function configurationClass() {
-  console.log('\n=== Example 6: Configuration Class ===\n');
-
-  console.log('✓ Application configuration:');
-  console.log(JSON.stringify(AppConfig.toJSON(), null, 2));
-}
-
-/**
- * Example 7: Practical use case - Database configuration
- */
-function databaseConfig() {
-  console.log('\n=== Example 7: Database Configuration ===\n');
-
-  // Set database environment variables
-  process.env.DB_HOST = 'localhost';
-  process.env.DB_PORT = '5432';
-  process.env.DB_NAME = 'myapp';
-  process.env.DB_USER = 'admin';
-  process.env.DB_PASSWORD = 'secret123';
-  process.env.DB_SSL = 'true';
-
-  // Build database configuration using Env helper
-  const dbConfig = {
-    host: Env.getString('DB_HOST', 'localhost'),
-    port: Env.getNumber('DB_PORT', 5432),
-    database: Env.getString('DB_NAME', 'myapp'),
-    username: Env.getStringOrThrow('DB_USER'),
-    password: Env.getStringOrThrow('DB_PASSWORD'),
-    ssl: Env.getBool('DB_SSL', false),
-  };
-
-  console.log('✓ Database configuration:');
-  console.log(JSON.stringify(dbConfig, null, 2));
-}
-
-/**
- * Example 8: Practical use case - Feature flags
- */
-function featureFlags() {
-  console.log('\n=== Example 8: Feature Flags ===\n');
-
-  // Set feature flags
-  process.env.FEATURE_CACHE = 'true';
-  process.env.FEATURE_LOGGING = '1';
-  process.env.FEATURE_METRICS = 'false';
-
-  // Read feature flags using Env helper
-  const features = {
-    cache: Env.getBool('FEATURE_CACHE', false),
-    logging: Env.getBool('FEATURE_LOGGING', false),
-    metrics: Env.getBool('FEATURE_METRICS', false),
-  };
-
-  console.log('✓ Feature flags:');
-  Object.entries(features).forEach(([name, enabled]) => {
-    console.log(`  - ${name}: ${enabled ? '✅ enabled' : '❌ disabled'}`);
-  });
-}
-
-/**
- * Example 9: Comparison with ConfigService
- */
-function comparisonWithConfigService() {
-  console.log('\n=== Example 9: Env vs ConfigService ===\n');
-
-  console.log('Env Helper:');
-  console.log('  ✅ No dependency injection needed');
-  console.log('  ✅ Static methods, easy to use anywhere');
-  console.log('  ✅ Perfect for simple scripts and utilities');
-  console.log('  ✅ Direct access to process.env');
-  console.log('  ❌ No driver support (env only)');
-  console.log('  ❌ No caching or advanced features');
-
-  console.log('\nConfigService:');
-  console.log('  ✅ Multiple driver support (env, file, etc.)');
-  console.log('  ✅ Dependency injection integration');
-  console.log('  ✅ Advanced features (caching, validation)');
-  console.log('  ✅ Better for large applications');
-  console.log('  ❌ Requires module setup');
-  console.log('  ❌ Needs dependency injection');
-}
-
-/**
- * Run all examples
- */
-function main() {
-  console.log('╔════════════════════════════════════════╗');
-  console.log('║   Env Helper Examples                  ║');
-  console.log('╚════════════════════════════════════════╝');
-
-  setupEnv();
-
-  basicUsage();
-  typeSafeGetters();
-  requiredValues();
-  checkExistence();
-  getAllEnv();
-  configurationClass();
-  databaseConfig();
-  featureFlags();
-  comparisonWithConfigService();
-
-  console.log('\n✅ All examples completed successfully!\n');
-}
-
-// Run the examples
-main();

package/.examples/README.md

@@ -1,285 +0,0 @@
-# Config Examples
-
-This folder contains examples demonstrating how to use `@abdokouta/config` in various scenarios.
-
-## Examples Overview
-
-### 1. Basic Usage (`01-basic-usage.ts`)
-
-Learn the fundamental configuration operations:
-- ✅ Environment variable access
-- ✅ Type-safe getters (getString, getNumber, getBool)
-- ✅ Default values
-- ✅ Nested configuration
-- ✅ JSON configuration
-- ✅ Array values
-
-**Run:**
-```bash
-ts-node examples/01-basic-usage.ts
-```
-
-### 2. Multiple Drivers (`02-multiple-drivers.ts`)
-
-Work with different configuration drivers:
-- ✅ Environment driver (dotenv)
-- ✅ File driver (TypeScript/JSON)
-- ✅ Switching between drivers
-- ✅ Driver-specific features
-- ✅ Configuration merging
-
-**Run:**
-```bash
-ts-node examples/02-multiple-drivers.ts
-```
-
-### 3. Env Helper (`03-env-helper.ts`)
-
-Use the standalone Env utility:
-- ✅ Direct environment access
-- ✅ Type conversions
-- ✅ No service injection needed
-- ✅ Static helper methods
-- ✅ Quick access patterns
-
-**Run:**
-```bash
-ts-node examples/03-env-helper.ts
-```
-
-## Quick Start
-
-### Installation
-
-```bash
-npm install @abdokouta/config @abdokouta/container
-```
-
-### Basic Setup
-
-```typescript
-import { ConfigModule, ConfigService } from '@abdokouta/config';
-import { Inversiland } from '@abdokouta/container';
-
-// Initialize config
-const app = await Inversiland.run({
-  module: class AppModule {},
-  imports: [
-    ConfigModule.forRoot({
-      driver: 'env',
-      envFilePath: '.env',
-      isGlobal: true,
-    }),
-  ],
-});
-
-// Get config service
-const config = app.get(ConfigService);
-
-// Use config
-const dbHost = config.getString('DB_HOST', 'localhost');
-const dbPort = config.getNumber('DB_PORT', 5432);
-```
-
-## Common Patterns
-
-### 1. Database Configuration
-
-```typescript
-const dbConfig = {
-  host: config.getString('DB_HOST', 'localhost'),
-  port: config.getNumber('DB_PORT', 5432),
-  database: config.getString('DB_NAME', 'myapp'),
-  username: config.getStringOrThrow('DB_USER'),
-  password: config.getStringOrThrow('DB_PASSWORD'),
-  ssl: config.getBool('DB_SSL', false),
-};
-```
-
-### 2. API Configuration
-
-```typescript
-const apiConfig = {
-  url: config.getString('API_URL', 'http://localhost:3000'),
-  timeout: config.getNumber('API_TIMEOUT', 5000),
-  retries: config.getNumber('API_RETRIES', 3),
-  apiKey: config.getStringOrThrow('API_KEY'),
-};
-```
-
-### 3. Feature Flags
-
-```typescript
-const features = {
-  enableCache: config.getBool('FEATURE_CACHE', true),
-  enableLogging: config.getBool('FEATURE_LOGGING', true),
-  enableMetrics: config.getBool('FEATURE_METRICS', false),
-};
-```
-
-### 4. Array Configuration
-
-```typescript
-const allowedOrigins = config.getArray('CORS_ORIGINS', ['http://localhost:3000']);
-const trustedProxies = config.getArray('TRUSTED_PROXIES', []);
-```
-
-### 5. JSON Configuration
-
-```typescript
-const complexConfig = config.getJson('APP_CONFIG', {
-  theme: 'light',
-  locale: 'en',
-  features: [],
-});
-```
-
-## Best Practices
-
-### 1. Use Type-Safe Getters
-
-```typescript
-// Good: Type-safe with defaults
-const port = config.getNumber('PORT', 3000);
-const debug = config.getBool('DEBUG', false);
-
-// Bad: Generic get without type safety
-const port = config.get('PORT') || 3000;
-```
-
-### 2. Require Critical Values
-
-```typescript
-// Use OrThrow for required configuration
-const apiKey = config.getStringOrThrow('API_KEY');
-const dbPassword = config.getStringOrThrow('DB_PASSWORD');
-```
-
-### 3. Group Related Configuration
-
-```typescript
-class DatabaseConfig {
-  constructor(private config: ConfigService) {}
-
-  get host() {
-    return this.config.getString('DB_HOST', 'localhost');
-  }
-
-  get port() {
-    return this.config.getNumber('DB_PORT', 5432);
-  }
-
-  get credentials() {
-    return {
-      username: this.config.getStringOrThrow('DB_USER'),
-      password: this.config.getStringOrThrow('DB_PASSWORD'),
-    };
-  }
-}
-```
-
-### 4. Use Environment-Specific Defaults
-
-```typescript
-const env = config.getString('NODE_ENV', 'development');
-
-const logLevel = config.getString(
-  'LOG_LEVEL',
-  env === 'production' ? 'error' : 'debug'
-);
-```
-
-### 5. Validate Configuration on Startup
-
-```typescript
-function validateConfig(config: ConfigService) {
-  const required = ['DB_HOST', 'DB_USER', 'DB_PASSWORD', 'API_KEY'];
-  
-  for (const key of required) {
-    if (!config.has(key)) {
-      throw new Error(`Missing required configuration: ${key}`);
-    }
-  }
-}
-```
-
-## Configuration Examples
-
-### Environment Driver
-
-```typescript
-ConfigModule.forRoot({
-  driver: 'env',
-  envFilePath: '.env',
-  ignoreEnvFile: false,
-  expandVariables: true,
-  isGlobal: true,
-})
-```
-
-### File Driver
-
-```typescript
-ConfigModule.forRoot({
-  driver: 'file',
-  load: {
-    database: {
-      host: 'localhost',
-      port: 5432,
-    },
-    api: {
-      url: 'http://localhost:3000',
-    },
-  },
-  isGlobal: true,
-})
-```
-
-### Custom Configuration
-
-```typescript
-ConfigModule.forRoot({
-  driver: 'env',
-  load: {
-    // Merge custom config with env vars
-    app: {
-      name: 'My App',
-      version: '1.0.0',
-    },
-  },
-  isGlobal: true,
-})
-```
-
-## Troubleshooting
-
-### Configuration Not Loading
-
-1. Check if ConfigModule is imported
-2. Verify .env file exists and is readable
-3. Check environment variable names
-4. Verify driver configuration
-
-### Type Conversion Issues
-
-1. Use appropriate getter methods
-2. Check default values
-3. Validate input format
-4. Use getOrThrow for debugging
-
-### Missing Values
-
-1. Use has() to check existence
-2. Provide sensible defaults
-3. Use getOrThrow for required values
-4. Check environment variable names
-
-## Additional Resources
-
-- [Main README](../README.md) - Package documentation
-- [NestJS Config Documentation](https://docs.nestjs.com/techniques/configuration) - Inspiration
-- [dotenv Documentation](https://github.com/motdotla/dotenv) - Environment variables
-
-## Contributing
-
-Found an issue or have a suggestion? Please open an issue or submit a pull request!

package/.prettierrc.js

@@ -1 +0,0 @@
-export default '@nesvel/prettier-config';