create-fluxstack 1.0.4 → 1.0.6

package/docs/dynamic-environment-variables.md

@@ -1,380 +0,0 @@
-# 🔄 Dynamic Environment Variables for FluxStack
-
-## 🚨 **Problema Resolvido**
-
-O **Bun build** fixa valores de `process.env` durante a compilação, impossibilitando mudanças de environment variables em produção sem rebuild.
-
-### ❌ **Problema Original**
-```typescript
-// Durante build, Bun converte isto:
-const port = process.env.PORT || 3000
-
-// Em isto (valor fixo):
-const port = "8080" || 3000  // Fixado no build!
-```
-
-### ✅ **Solução FluxStack**
-```typescript
-import { env } from '@/core/utils/env-runtime'
-
-// Sempre dinâmico, mesmo após build:
-const port = env.num('PORT', 3000)  // 🚀 Funciona em runtime!
-```
-
----
-
-## 🛠️ **Como Usar**
-
-### **1. Import Básico**
-```typescript
-import { env } from '@/core/utils/env-runtime'
-
-// Métodos disponíveis:
-const port = env.num('PORT', 3000)           // number
-const host = env.get('HOST', 'localhost')    // string  
-const debug = env.bool('DEBUG', false)       // boolean
-const origins = env.array('CORS_ORIGINS')    // string[]
-const hasDb = env.has('DATABASE_URL')        // boolean
-```
-
-### **2. Propriedades Shorthand**
-```typescript
-// Acesso direto para vars comuns:
-console.log(env.PORT)          // number
-console.log(env.NODE_ENV)      // string
-console.log(env.DATABASE_URL)  // string | undefined
-console.log(env.CORS_ORIGINS)  // string[]
-```
-
-### **3. Configuração de Servidor**
-```typescript
-import { createRuntimeConfig } from '@/core/config/runtime-config'
-
-const config = createRuntimeConfig({
-  server: {
-    port: env.num('PORT', 3000),
-    host: env.get('HOST', 'localhost')
-  }
-})
-
-const app = new FluxStackFramework(config)
-```
-
-### **4. Diferentes Ambientes**
-```typescript
-import { runtimeConfig } from '@/core/config/runtime-config'
-
-// Auto-detect do ambiente:
-const config = runtimeConfig.auto()
-
-// Ou específico:
-const devConfig = runtimeConfig.development()
-const prodConfig = runtimeConfig.production()
-const testConfig = runtimeConfig.test()
-```
-
----
-
-## 🔧 **Migração do Código Existente**
-
-### **Antes (Fixado pelo Bun)**
-```typescript
-// ❌ Será fixado durante build
-const oldConfig = {
-  port: parseInt(process.env.PORT || '3000'),
-  dbUrl: process.env.DATABASE_URL,
-  debug: process.env.DEBUG === 'true',
-  corsOrigins: process.env.CORS_ORIGINS?.split(',') || ['*'],
-  enableMonitoring: process.env.MONITORING_ENABLED === 'true'
-}
-```
-
-### **Depois (Dinâmico)**
-```typescript
-// ✅ Sempre dinâmico, mesmo após build
-import { env } from '@/core/utils/env-runtime'
-
-const newConfig = {
-  port: env.num('PORT', 3000),
-  dbUrl: env.get('DATABASE_URL'),
-  debug: env.bool('DEBUG', false),
-  corsOrigins: env.array('CORS_ORIGINS', ['*']),
-  enableMonitoring: env.bool('MONITORING_ENABLED', false)
-}
-```
-
----
-
-## 🏗️ **Configuração Avançada**
-
-### **1. Namespaces de Environment**
-```typescript
-import { createEnvNamespace } from '@/core/utils/env-runtime'
-
-// Criar loaders especializados
-const dbEnv = createEnvNamespace('DATABASE_')
-const redisEnv = createEnvNamespace('REDIS_')
-const awsEnv = createEnvNamespace('AWS_')
-
-// Uso:
-const dbConfig = {
-  url: dbEnv.get('URL'),        // DATABASE_URL
-  host: dbEnv.get('HOST'),      // DATABASE_HOST
-  port: dbEnv.getNumber('PORT') // DATABASE_PORT
-}
-```
-
-### **2. Validação de Environment**
-```typescript
-import { envValidation } from '@/core/utils/env-runtime'
-
-// Validar vars obrigatórias
-envValidation.require(['NODE_ENV', 'DATABASE_URL'])
-
-// Validar formato
-envValidation.validate('DATABASE_URL', 
-  (url) => url.includes('://'),
-  'DATABASE_URL deve ser uma URL válida'
-)
-```
-
-### **3. Configuração Condicional**
-```typescript
-import { env } from '@/core/utils/env-runtime'
-
-export function createServerConfig() {
-  const config = {
-    port: env.num('PORT', 3000),
-    
-    // Database apenas se configurado
-    ...(env.has('DATABASE_URL') && {
-      database: {
-        url: env.get('DATABASE_URL'),
-        ssl: env.bool('DB_SSL', env.get('NODE_ENV') === 'production')
-      }
-    }),
-    
-    // Features baseadas no ambiente
-    features: {
-      swagger: env.bool('ENABLE_SWAGGER', env.get('NODE_ENV') !== 'production'),
-      monitoring: env.bool('ENABLE_MONITORING', env.get('NODE_ENV') === 'production')
-    }
-  }
-  
-  return config
-}
-```
-
----
-
-## 🚀 **Integração com FluxStack**
-
-### **1. Servidor com Env Dinâmico**
-```typescript
-import { FluxStackFramework } from '@/core/framework/server'
-import { createRuntimeConfig } from '@/core/config/runtime-config'
-import { env } from '@/core/utils/env-runtime'
-
-export async function startServer() {
-  // Configuração dinâmica
-  const config = createRuntimeConfig()
-  
-  // Framework com env dinâmico
-  const app = new FluxStackFramework(config)
-  
-  // Plugins condicionais
-  if (env.bool('ENABLE_SWAGGER', true)) {
-    app.use(swaggerPlugin)
-  }
-  
-  if (env.bool('ENABLE_MONITORING', false)) {
-    app.use(monitoringPlugin)
-  }
-  
-  await app.listen()
-  
-  console.log(`🚀 Server running on port ${env.num('PORT', 3000)}`)
-}
-```
-
-### **2. Build Configuration**
-```typescript
-// No fluxstack.config.ts
-import { env } from '@/core/utils/env-runtime'
-
-export const config = {
-  app: {
-    name: env.get('FLUXSTACK_APP_NAME', 'my-app'),
-    version: env.get('FLUXSTACK_APP_VERSION', '1.0.0')
-  },
-  
-  server: {
-    port: env.num('PORT', 3000),
-    host: env.get('HOST', 'localhost'),
-    cors: {
-      origins: env.array('CORS_ORIGINS', ['*'])
-    }
-  },
-  
-  build: {
-    target: env.get('BUILD_TARGET', 'bun'),
-    outDir: env.get('BUILD_OUTDIR', 'dist'),
-    optimization: {
-      minify: env.bool('BUILD_MINIFY', env.get('NODE_ENV') === 'production')
-    }
-  }
-}
-```
-
----
-
-## 🧪 **Testando com Env Dinâmico**
-
-### **1. Configuração de Teste**
-```typescript
-import { runtimeConfig } from '@/core/config/runtime-config'
-
-// Configuração isolada para testes
-const testConfig = runtimeConfig.test()
-
-// Ou com overrides específicos
-const config = runtimeConfig.auto({
-  server: { port: 0 }, // Porta aleatória
-  database: { url: 'sqlite://memory:' }
-})
-```
-
-### **2. Mock de Environment Variables**
-```typescript
-import { withTestEnv } from '@/examples/dynamic-env-usage'
-
-test('server configuration with custom env', () => {
-  withTestEnv({
-    'PORT': '9000',
-    'NODE_ENV': 'test',
-    'DEBUG': 'true'
-  }, () => {
-    const config = createServerConfig()
-    expect(config.port).toBe(9000)
-    expect(config.debug).toBe(true)
-  })
-})
-```
-
----
-
-## 📦 **Deploy e Produção**
-
-### **1. Docker com Env Dinâmico**
-```dockerfile
-# Dockerfile
-FROM oven/bun:1.1-alpine
-
-WORKDIR /app
-COPY . .
-
-# Build com env dinâmico funcionando
-RUN bun run build
-
-# Environment variables não fixadas no build
-ENV NODE_ENV=production
-ENV PORT=3000
-
-CMD ["bun", "run", "dist/index.js"]
-```
-
-### **2. Docker Compose**
-```yaml
-# docker-compose.yml
-version: '3.8'
-services:
-  app:
-    build: .
-    ports:
-      - "${PORT:-3000}:${PORT:-3000}"
-    environment:
-      - NODE_ENV=production
-      - PORT=${PORT:-3000}
-      - DATABASE_URL=${DATABASE_URL}
-      - JWT_SECRET=${JWT_SECRET}
-      - CORS_ORIGINS=${CORS_ORIGINS:-*}
-      - ENABLE_MONITORING=${ENABLE_MONITORING:-true}
-```
-
-### **3. Deploy com Variáveis Dinâmicas**
-```bash
-# Build uma vez
-bun run build
-
-# Deploy em diferentes ambientes (sem rebuild!)
-NODE_ENV=staging PORT=4000 bun run dist/index.js
-NODE_ENV=production PORT=8080 DATABASE_URL=postgres://... bun run dist/index.js
-```
-
----
-
-## ⚡ **Performance e Compatibilidade**
-
-### **Overhead**
-- **Mínimo**: Apenas uma verificação extra por acesso
-- **Cache**: Valores são cached dentro da mesma execução
-- **Bun.env**: Usa Bun.env quando disponível (mais rápido)
-
-### **Compatibilidade**
-- ✅ **Bun runtime**: Usa `Bun.env` otimizado
-- ✅ **Node.js**: Fallback para `process.env`
-- ✅ **Build tools**: Resistente a otimizações
-- ✅ **Testing**: Funciona com mocks
-
-### **Fallbacks**
-1. `Bun.env` (mais rápido no Bun)
-2. `process.env` (Node.js/fallback)
-3. `eval('process')` (edge cases)
-
----
-
-## 🔍 **Debugging**
-
-### **Ver Todas as Environment Variables**
-```typescript
-import { env } from '@/core/utils/env-runtime'
-
-// Listar todas as env vars
-console.log(env.all())
-
-// Verificar se existe
-if (env.has('DATABASE_URL')) {
-  console.log('Database configured')
-}
-
-// Debug de configuração
-console.log('🔧 Current config:')
-console.log(`  NODE_ENV: ${env.get('NODE_ENV')}`)
-console.log(`  PORT: ${env.num('PORT', 3000)}`)
-console.log(`  DEBUG: ${env.bool('DEBUG')}`)
-```
-
----
-
-## 📋 **Checklist de Migração**
-
-- [ ] Substituir `process.env.VAR` por `env.get('VAR')`
-- [ ] Usar `env.num()`, `env.bool()`, `env.array()` conforme tipo
-- [ ] Atualizar configuração do FluxStack
-- [ ] Testar em desenvolvimento
-- [ ] Testar build e produção
-- [ ] Verificar Docker/deploy
-- [ ] Documentar env vars específicas do projeto
-
----
-
-## 🎯 **Benefícios**
-
-✅ **Env vars dinâmicas** mesmo após Bun build  
-✅ **Deploy flexível** sem rebuild  
-✅ **Type-safe** com conversão automática  
-✅ **Validação** de env vars obrigatórias  
-✅ **Namespace** para organização  
-✅ **Compatibilidade** com Node.js e Bun  
-✅ **Performance** otimizada  
-✅ **Testing** friendly

package/examples/dynamic-env-usage.ts

@@ -1,283 +0,0 @@
-/**
- * Exemplos de como usar o sistema de Environment Variables dinâmico
- * Solução para o problema do Bun build fixar valores de process.env
- */
-
-// ========================================
-// 1. IMPORT DO SISTEMA DINÂMICO
-// ========================================
-
-import { env, runtimeEnv, envValidation } from '../core/utils/env-runtime'
-import { createRuntimeConfig, runtimeConfig, configHelpers } from '../core/config/runtime-config'
-import { dynamicEnvironmentProcessor } from '../core/config/env-dynamic'
-
-// ========================================
-// 2. USO BÁSICO - Substituir process.env
-// ========================================
-
-// ❌ ANTES (fixado pelo Bun build):
-// const port = process.env.PORT || 3000
-// const dbUrl = process.env.DATABASE_URL
-
-// ✅ DEPOIS (dinâmico em runtime):
-const port = env.num('PORT', 3000)
-const dbUrl = env.get('DATABASE_URL')
-const isDebug = env.bool('DEBUG', false)
-const corsOrigins = env.array('CORS_ORIGINS', ['*'])
-
-console.log('🚀 Server will start on port:', port) // Valor dinâmico!
-
-// ========================================
-// 3. CONFIGURAÇÃO DE SERVIDOR DINÂMICA
-// ========================================
-
-export function createDynamicServer() {
-  // Configuração que funciona em produção sem rebuild
-  const serverConfig = {
-    port: env.num('PORT', 3000),
-    host: env.get('HOST', 'localhost'),
-    
-    // Database dinâmico
-    database: {
-      url: env.get('DATABASE_URL'),
-      maxConnections: env.num('DB_MAX_CONNECTIONS', 10),
-      ssl: env.bool('DB_SSL', env.get('NODE_ENV') === 'production')
-    },
-    
-    // CORS dinâmico
-    cors: {
-      origins: env.array('CORS_ORIGINS', ['*']),
-      credentials: env.bool('CORS_CREDENTIALS', false)
-    },
-    
-    // JWT dinâmico
-    jwt: {
-      secret: env.get('JWT_SECRET') || generateSecret(),
-      expiresIn: env.get('JWT_EXPIRES_IN', '24h')
-    },
-    
-    // Features dinâmicas
-    features: {
-      monitoring: env.bool('ENABLE_MONITORING', env.get('NODE_ENV') === 'production'),
-      metrics: env.bool('ENABLE_METRICS', false),
-      swagger: env.bool('ENABLE_SWAGGER', env.get('NODE_ENV') !== 'production')
-    }
-  }
-  
-  return serverConfig
-}
-
-// ========================================
-// 4. FLUXSTACK COM ENV DINÂMICO
-// ========================================
-
-import { FluxStackFramework } from '../core/framework/server'
-
-export function createFluxStackWithDynamicEnv() {
-  // Usar configuração runtime dinâmica
-  const config = createRuntimeConfig({
-    // Overrides específicos
-    server: {
-      port: env.num('PORT', 3000),
-      host: env.get('HOST', 'localhost'),
-    }
-  })
-  
-  const app = new FluxStackFramework(config)
-  
-  // Configurações que mudam em runtime
-  if (env.bool('ENABLE_SWAGGER', true)) {
-    // Swagger só se habilitado
-  }
-  
-  if (env.bool('ENABLE_MONITORING', false)) {
-    // Monitoring só se habilitado
-  }
-  
-  return app
-}
-
-// ========================================
-// 5. DIFERENTES AMBIENTES
-// ========================================
-
-export function createEnvironmentSpecificConfig() {
-  const environment = env.get('NODE_ENV', 'development')
-  
-  switch (environment) {
-    case 'development':
-      return runtimeConfig.development()
-    
-    case 'production':
-      return runtimeConfig.production()
-    
-    case 'test':
-      return runtimeConfig.test()
-    
-    default:
-      return runtimeConfig.auto()
-  }
-}
-
-// ========================================
-// 6. VALIDAÇÃO DE ENV VARS
-// ========================================
-
-export function validateEnvironment() {
-  // Validar vars obrigatórias
-  envValidation.require(['NODE_ENV'])
-  
-  // Se production, validar mais vars
-  if (env.get('NODE_ENV') === 'production') {
-    envValidation.require([
-      'DATABASE_URL',
-      'JWT_SECRET'
-    ])
-    
-    // Validar formato
-    envValidation.validate('DATABASE_URL', 
-      (url) => url.includes('://'),
-      'DATABASE_URL deve ser uma URL válida'
-    )
-  }
-}
-
-// ========================================
-// 7. CONFIGURAÇÃO POR NAMESPACE
-// ========================================
-
-import { createEnvNamespace } from '../core/utils/env-runtime'
-
-// Criar loaders especializados
-const dbEnv = createEnvNamespace('DATABASE_')
-const redisEnv = createEnvNamespace('REDIS_')
-const awsEnv = createEnvNamespace('AWS_')
-
-export function createDatabaseConfig() {
-  return {
-    url: dbEnv.get('URL'),           // DATABASE_URL
-    host: dbEnv.get('HOST'),         // DATABASE_HOST
-    port: dbEnv.getNumber('PORT'),   // DATABASE_PORT
-    ssl: dbEnv.getBoolean('SSL'),    // DATABASE_SSL
-  }
-}
-
-export function createRedisConfig() {
-  return {
-    url: redisEnv.get('URL'),        // REDIS_URL
-    host: redisEnv.get('HOST'),      // REDIS_HOST
-    port: redisEnv.getNumber('PORT'), // REDIS_PORT
-  }
-}
-
-// ========================================
-// 8. CONFIGURAÇÃO HELPERS
-// ========================================
-
-export function getAppConfig() {
-  return {
-    // Server config dinâmico
-    server: configHelpers.getServerConfig(),
-    
-    // Client config dinâmico  
-    client: configHelpers.getClientConfig(),
-    
-    // Database com validação
-    database: configHelpers.getDatabaseUrl(),
-    
-    // CORS com defaults inteligentes
-    cors: configHelpers.getCorsOrigins()
-  }
-}
-
-// ========================================
-// 9. EXEMPLO COMPLETO DE USO
-// ========================================
-
-export async function startFluxStackServer() {
-  console.log('🔧 Validating environment...')
-  validateEnvironment()
-  
-  console.log('⚙️  Loading dynamic configuration...')
-  const config = createEnvironmentSpecificConfig()
-  
-  console.log('🚀 Starting FluxStack with dynamic env...')
-  const app = new FluxStackFramework(config)
-  
-  // Log das configurações atuais (valores dinâmicos!)
-  console.log('📊 Configuration loaded:')
-  console.log(`   Environment: ${env.get('NODE_ENV')}`)
-  console.log(`   Port: ${env.num('PORT', 3000)}`)
-  console.log(`   Database: ${env.get('DATABASE_URL') ? '✅ Connected' : '❌ Not configured'}`)
-  console.log(`   Monitoring: ${env.bool('ENABLE_MONITORING') ? '✅ Enabled' : '❌ Disabled'}`)
-  
-  await app.listen()
-  
-  console.log('✅ Server started with dynamic environment variables!')
-}
-
-// ========================================
-// 10. MIGRANDO CÓDIGO EXISTENTE
-// ========================================
-
-// ❌ Código antigo que será fixado pelo Bun:
-export const oldConfig = {
-  port: parseInt(process.env.PORT || '3000'),
-  dbUrl: process.env.DATABASE_URL,
-  debug: process.env.DEBUG === 'true'
-}
-
-// ✅ Código novo que funciona dinamicamente:
-export const newConfig = {
-  port: env.num('PORT', 3000),
-  dbUrl: env.get('DATABASE_URL'),
-  debug: env.bool('DEBUG', false)
-}
-
-// ========================================
-// 11. TESTES COM ENV DINÂMICO
-// ========================================
-
-export function createTestConfig() {
-  // Configuração para testes que não interfere com env vars reais
-  return runtimeConfig.test()
-}
-
-// Helper para simular env vars em testes
-export function withTestEnv(envVars: Record<string, string>, fn: () => void) {
-  const original = { ...runtimeEnv.all() }
-  
-  // Simular env vars
-  Object.assign(process.env, envVars)
-  
-  try {
-    fn()
-  } finally {
-    // Restaurar env original
-    Object.keys(envVars).forEach(key => {
-      if (original[key] !== undefined) {
-        process.env[key] = original[key]
-      } else {
-        delete process.env[key]
-      }
-    })
-  }
-}
-
-// Função helper para gerar secret se não existir
-function generateSecret(): string {
-  console.warn('⚠️  JWT_SECRET not found, generating random secret for development')
-  return Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15)
-}
-
-// ========================================
-// 12. EXPORT DEFAULT
-// ========================================
-
-export default {
-  createDynamicServer,
-  createFluxStackWithDynamicEnv,
-  validateEnvironment,
-  startFluxStackServer,
-  getAppConfig
-}