@abdokouta/react-config 1.0.1 → 1.0.2

package/.examples/01-basic-usage.ts

@@ -1,291 +0,0 @@
-/**
- * Basic Config Usage Example
- *
- * This example demonstrates the fundamental configuration operations:
- * - Environment variable access
- * - Type-safe getters
- * - Default values
- * - Nested configuration
- *
- * @example
- * Run this example:
- * ```bash
- * ts-node examples/01-basic-usage.ts
- * ```
- */
-
-import { ConfigModule, ConfigService } from '@abdokouta/config';
-import { Inversiland } from '@abdokouta/react-di';
-
-/**
- * Initialize the config module
- */
-async function setupConfig() {
-  // Set some example environment variables
-  process.env.APP_NAME = 'My Application';
-  process.env.APP_PORT = '3000';
-  process.env.APP_DEBUG = 'true';
-  process.env.APP_URL = 'http://localhost:3000';
-  process.env.ALLOWED_HOSTS = 'localhost,127.0.0.1,example.com';
-  process.env.DATABASE_CONFIG = JSON.stringify({
-    host: 'localhost',
-    port: 5432,
-    database: 'myapp',
-  });
-
-  // Create the application module with config
-  const app = await Inversiland.run({
-    module: class AppModule {},
-    imports: [
-      ConfigModule.forRoot({
-        driver: 'env',
-        ignoreEnvFile: true, // Use process.env directly for this example
-        isGlobal: true,
-      }),
-    ],
-  });
-
-  return app.get(ConfigService);
-}
-
-/**
- * Example 1: Basic string values
- */
-function stringValues(config: ConfigService) {
-  console.log('\n=== Example 1: String Values ===\n');
-
-  // Get string value
-  const appName = config.getString('APP_NAME');
-  console.log(`✓ APP_NAME: "${appName}"`);
-
-  // Get string with default
-  const appEnv = config.getString('APP_ENV', 'development');
-  console.log(`✓ APP_ENV: "${appEnv}" (using default)`);
-
-  // Get URL
-  const appUrl = config.getString('APP_URL');
-  console.log(`✓ APP_URL: "${appUrl}"`);
-}
-
-/**
- * Example 2: Number values
- */
-function numberValues(config: ConfigService) {
-  console.log('\n=== Example 2: Number Values ===\n');
-
-  // Get number value
-  const port = config.getNumber('APP_PORT');
-  console.log(`✓ APP_PORT: ${port} (type: ${typeof port})`);
-
-  // Get number with default
-  const timeout = config.getNumber('APP_TIMEOUT', 5000);
-  console.log(`✓ APP_TIMEOUT: ${timeout} (using default)`);
-
-  // Get number that doesn't exist
-  const maxConnections = config.getNumber('MAX_CONNECTIONS', 100);
-  console.log(`✓ MAX_CONNECTIONS: ${maxConnections} (using default)`);
-}
-
-/**
- * Example 3: Boolean values
- */
-function booleanValues(config: ConfigService) {
-  console.log('\n=== Example 3: Boolean Values ===\n');
-
-  // Get boolean value (true)
-  const debug = config.getBool('APP_DEBUG');
-  console.log(`✓ APP_DEBUG: ${debug} (type: ${typeof debug})`);
-
-  // Get boolean with default
-  const enableCache = config.getBool('ENABLE_CACHE', true);
-  console.log(`✓ ENABLE_CACHE: ${enableCache} (using default)`);
-
-  // Test various boolean formats
-  process.env.TEST_TRUE_1 = 'true';
-  process.env.TEST_TRUE_2 = '1';
-  process.env.TEST_TRUE_3 = 'yes';
-  process.env.TEST_TRUE_4 = 'on';
-  process.env.TEST_FALSE = 'false';
-
-  console.log(`✓ "true" → ${config.getBool('TEST_TRUE_1')}`);
-  console.log(`✓ "1" → ${config.getBool('TEST_TRUE_2')}`);
-  console.log(`✓ "yes" → ${config.getBool('TEST_TRUE_3')}`);
-  console.log(`✓ "on" → ${config.getBool('TEST_TRUE_4')}`);
-  console.log(`✓ "false" → ${config.getBool('TEST_FALSE')}`);
-}
-
-/**
- * Example 4: Array values
- */
-function arrayValues(config: ConfigService) {
-  console.log('\n=== Example 4: Array Values ===\n');
-
-  // Get array from comma-separated string
-  const allowedHosts = config.getArray('ALLOWED_HOSTS');
-  console.log(`✓ ALLOWED_HOSTS:`, allowedHosts);
-
-  // Get array with default
-  const corsOrigins = config.getArray('CORS_ORIGINS', ['http://localhost:3000']);
-  console.log(`✓ CORS_ORIGINS:`, corsOrigins, '(using default)');
-
-  // Empty array
-  const emptyArray = config.getArray('EMPTY_ARRAY', []);
-  console.log(`✓ EMPTY_ARRAY:`, emptyArray, '(using default)');
-}
-
-/**
- * Example 5: JSON values
- */
-function jsonValues(config: ConfigService) {
-  console.log('\n=== Example 5: JSON Values ===\n');
-
-  // Get JSON object
-  const dbConfig = config.getJson('DATABASE_CONFIG');
-  console.log(`✓ DATABASE_CONFIG:`, dbConfig);
-
-  // Get JSON with default
-  const apiConfig = config.getJson('API_CONFIG', {
-    url: 'http://localhost:3000',
-    timeout: 5000,
-  });
-  console.log(`✓ API_CONFIG:`, apiConfig, '(using default)');
-}
-
-/**
- * Example 6: Check if keys exist
- */
-function checkExistence(config: ConfigService) {
-  console.log('\n=== Example 6: Check Existence ===\n');
-
-  // Check existing key
-  const hasAppName = config.has('APP_NAME');
-  console.log(`✓ has('APP_NAME'): ${hasAppName}`);
-
-  // Check non-existent key
-  const hasApiKey = config.has('API_KEY');
-  console.log(`✓ has('API_KEY'): ${hasApiKey}`);
-}
-
-/**
- * Example 7: Required values (OrThrow)
- */
-function requiredValues(config: ConfigService) {
-  console.log('\n=== Example 7: Required Values ===\n');
-
-  try {
-    // Get required value that exists
-    const appName = config.getStringOrThrow('APP_NAME');
-    console.log(`✓ getStringOrThrow('APP_NAME'): "${appName}"`);
-
-    // Try to get required value that doesn't exist
-    const apiKey = config.getStringOrThrow('API_KEY');
-    console.log(`✓ getStringOrThrow('API_KEY'): "${apiKey}"`);
-  } catch (error) {
-    console.log(`✗ Error: ${(error as Error).message}`);
-    console.log(`  💡 Use OrThrow methods for required configuration`);
-  }
-}
-
-/**
- * Example 8: Get all configuration
- */
-function getAllConfig(config: ConfigService) {
-  console.log('\n=== Example 8: Get All Configuration ===\n');
-
-  const allConfig = config.all();
-  const keys = Object.keys(allConfig).filter(
-    (k) => k.startsWith('APP_') || k.startsWith('ALLOWED_')
-  );
-
-  console.log('✓ All APP_* and ALLOWED_* configuration:');
-  keys.forEach((key) => {
-    console.log(`  - ${key}: ${allConfig[key]}`);
-  });
-}
-
-/**
- * Example 9: Practical use case - Database configuration
- */
-function databaseConfig(config: ConfigService) {
-  console.log('\n=== Example 9: 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';
-  process.env.DB_POOL_MIN = '2';
-  process.env.DB_POOL_MAX = '10';
-
-  // Build database configuration object
-  const dbConfig = {
-    host: config.getString('DB_HOST', 'localhost'),
-    port: config.getNumber('DB_PORT', 5432),
-    database: config.getString('DB_NAME', 'myapp'),
-    username: config.getString('DB_USER'),
-    password: config.getString('DB_PASSWORD'),
-    ssl: config.getBool('DB_SSL', false),
-    pool: {
-      min: config.getNumber('DB_POOL_MIN', 2),
-      max: config.getNumber('DB_POOL_MAX', 10),
-    },
-  };
-
-  console.log('✓ Database configuration:');
-  console.log(JSON.stringify(dbConfig, null, 2));
-}
-
-/**
- * Example 10: Practical use case - Feature flags
- */
-function featureFlags(config: ConfigService) {
-  console.log('\n=== Example 10: Feature Flags ===\n');
-
-  // Set feature flags
-  process.env.FEATURE_CACHE = 'true';
-  process.env.FEATURE_LOGGING = 'true';
-  process.env.FEATURE_METRICS = 'false';
-  process.env.FEATURE_ANALYTICS = '1';
-
-  // Read feature flags
-  const features = {
-    cache: config.getBool('FEATURE_CACHE', false),
-    logging: config.getBool('FEATURE_LOGGING', false),
-    metrics: config.getBool('FEATURE_METRICS', false),
-    analytics: config.getBool('FEATURE_ANALYTICS', false),
-  };
-
-  console.log('✓ Feature flags:');
-  Object.entries(features).forEach(([name, enabled]) => {
-    console.log(`  - ${name}: ${enabled ? '✅ enabled' : '❌ disabled'}`);
-  });
-}
-
-/**
- * Run all examples
- */
-async function main() {
-  console.log('╔════════════════════════════════════════╗');
-  console.log('║   Config Basic Usage Examples          ║');
-  console.log('╚════════════════════════════════════════╝');
-
-  const config = await setupConfig();
-
-  stringValues(config);
-  numberValues(config);
-  booleanValues(config);
-  arrayValues(config);
-  jsonValues(config);
-  checkExistence(config);
-  requiredValues(config);
-  getAllConfig(config);
-  databaseConfig(config);
-  featureFlags(config);
-
-  console.log('\n✅ All examples completed successfully!\n');
-}
-
-// Run the examples
-main().catch(console.error);

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();