@arc-js/config-manager 0.0.1

package/README.md

@@ -0,0 +1,608 @@
+# @arc-js/config-manager
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-007ACC)
+![React](https://img.shields.io/badge/React-19+-61DAFB)
+![Vite](https://img.shields.io/badge/Vite-6+-646CFF)
+
+**@arc-js/config-manager** est un système de gestion de configuration modulaire pour les applications React avec TypeScript/JavaScript. Il fournit une gestion centralisée des configurations, un chargement dynamique des modules, et une intégration transparente avec les variables d'environnement.
+
+## ✨ Fonctionnalités Principales
+
+### ⚙️ Gestion Modulaire des Configurations
+- **Configurations hiérarchiques** avec fusion intelligente
+- **Chargement dynamique** des fichiers de configuration
+- **Support des modules indépendants** avec isolation
+- **Héritage automatique** de la configuration globale
+
+### 🔌 Intégration Environnement
+- **Variables d'environnement** automatiquement chargées (module `ENV`)
+- **Support Vite et Node.js** (process.env)
+- **Typage fort** pour les configurations
+- **Validation des chemins** avec fallback sécurisé
+
+### 🚀 Performance Optimisée
+- **Chargement paresseux** des configurations
+- **Cache mémoire** pour les accès répétés
+- **Hot reload** pendant le développement
+- **Minimal bundle size**
+
+### 🛡️ Sécurité et Fiabilité
+- **Gestion des erreurs** avec valeurs par défaut
+- **Validation des chemins** avant accès
+- **Logs en mode développement** uniquement
+- **Types TypeScript complets**
+
+## 📦 Installation
+
+```bash
+npm install @arc-js/config-manager
+# ou
+yarn add @arc-js/config-manager
+# ou
+pnpm add @arc-js/config-manager
+```
+
+### Dépendances requises
+- React 19+
+- TypeScript 5.0+ (recommandé)
+- Vite (pour le chargement dynamique)
+
+## 🚀 Démarrage Rapide
+
+### Structure de projet recommandée
+
+```
+src/
+├── config.json                    # Configuration globale
+├── modules/
+│   ├── admin/
+│   │   └── config.json           # Configuration du module admin
+│   ├── dashboard/
+│   │   └── config.json           # Configuration du module dashboard
+│   └── api/
+│       └── config.json           # Configuration du module API
+└── main.tsx
+```
+
+### Configuration de base
+
+```json
+// src/config.json (Configuration globale)
+{
+  "app": {
+    "name": "Mon Application",
+    "version": "1.0.0",
+    "debug": false,
+    "features": {
+      "analytics": true,
+      "notifications": false
+    }
+  },
+  "api": {
+    "baseUrl": "https://api.example.com",
+    "timeout": 30000,
+    "retryAttempts": 3
+  },
+  "ui": {
+    "theme": "light",
+    "language": "fr"
+  }
+}
+```
+
+```json
+// src/modules/admin/config.json (Module admin)
+{
+  "app": {
+    "name": "Admin Panel", // Écrase le nom global pour ce module
+    "debug": true // Surcharge le debug global
+  },
+  "admin": {
+    "permissions": ["users:read", "users:write", "settings:manage"],
+    "dashboard": {
+      "refreshInterval": 5000,
+      "maxItems": 100
+    }
+  }
+}
+```
+
+### Utilisation de base
+
+```typescript
+// main.tsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { ConfigProvider } from '@arc-js/config-manager';
+
+const App = () => {
+  return (
+    <div>
+      <h1>Mon Application Configurée</h1>
+    </div>
+  );
+};
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <ConfigProvider preloadModules={['admin', 'dashboard']}>
+      <App />
+    </ConfigProvider>
+  </React.StrictMode>
+);
+```
+
+## 📚 Documentation API
+
+### Hook useConfig
+
+```typescript
+import { useConfig } from '@arc-js/config-manager';
+
+const MyComponent = () => {
+  const config = useConfig('admin'); // Optionnel: nom du module
+
+  // Récupérer une valeur avec chemin pointé
+  const appName = config.get('app.name');
+  const apiTimeout = config.get('api.timeout');
+  
+  // Récupérer avec valeur par défaut
+  const debugMode = config.get('app.debug', { defaultValue: false });
+  
+  // Récupérer ou lancer une exception si non trouvé
+  const baseUrl = config.getOrThrow('api.baseUrl');
+  
+  // Vérifier l'existence d'un chemin
+  const hasAnalytics = config.has('app.features.analytics');
+  
+  // Récupérer toutes les configurations
+  const allConfigs = config.getAll();
+  
+  // Accès aux variables d'environnement
+  const nodeEnv = config.getEnv('NODE_ENV');
+  const apiUrl = config.getEnv('apiUrl'); // VITE_API_URL
+  
+  return (
+    <div>
+      <h1>{appName}</h1>
+      <p>API Timeout: {apiTimeout}ms</p>
+      <p>Environment: {nodeEnv}</p>
+    </div>
+  );
+};
+```
+
+### Hook useConfigValue (Typé)
+
+```typescript
+import { useConfigValue } from '@arc-js/config-manager';
+
+const FeatureToggle = () => {
+  const { value: isEnabled, isLoading, exists } = 
+    useConfigValue<boolean>('app.features.analytics', {
+      moduleName: 'admin',
+      defaultValue: false
+    });
+
+  if (isLoading) return <div>Chargement...</div>;
+  
+  return (
+    <div>
+      <p>Analytics: {isEnabled ? 'Activé' : 'Désactivé'}</p>
+      <p>Configuration existante: {exists ? 'Oui' : 'Non'}</p>
+    </div>
+  );
+};
+```
+
+### Modifier une configuration
+
+```typescript
+const SettingsPanel = () => {
+  const config = useConfig();
+  
+  const toggleDebug = () => {
+    const currentDebug = config.get('app.debug', { defaultValue: false });
+    config.set('app.debug', !currentDebug);
+  };
+  
+  const updateApiConfig = () => {
+    config.merge({
+      api: {
+        timeout: 60000,
+        retryAttempts: 5
+      }
+    }, 'admin'); // Appliquer uniquement au module admin
+  };
+  
+  return (
+    <div>
+      <button onClick={toggleDebug}>
+        Toggle Debug Mode
+      </button>
+      <button onClick={updateApiConfig}>
+        Update API Settings
+      </button>
+    </div>
+  );
+};
+```
+
+## 🔧 Utilisation Avancée
+
+### Variables d'environnement
+
+```bash
+# .env
+VITE_API_URL=https://api.example.com
+VITE_APP_NAME="My App"
+VITE_DEBUG=true
+NODE_ENV=development
+```
+
+```typescript
+const EnvironmentInfo = () => {
+  const config = useConfig();
+  
+  // Accès aux variables VITE_*
+  const apiUrl = config.getEnv('apiUrl'); // VITE_API_URL
+  const appName = config.getEnv('appName'); // VITE_APP_NAME
+  
+  // Ou via le module ENV
+  const viteApiUrl = config.get('apiUrl', { moduleName: 'ENV' });
+  
+  // Vérifier l'environnement
+  const isProd = config.isProduction();
+  const isDev = config.isDevelopment();
+  const isTest = config.isTest();
+  
+  return (
+    <div>
+      <h2>Environment Configuration</h2>
+      <p>API URL: {apiUrl}</p>
+      <p>App Name: {appName}</p>
+      <p>Mode: {isProd ? 'Production' : isDev ? 'Development' : 'Test'}</p>
+    </div>
+  );
+};
+```
+
+### Configuration hiérarchique complexe
+
+```json
+// src/modules/complex/config.json
+{
+  "database": {
+    "connections": {
+      "primary": {
+        "host": "localhost",
+        "port": 5432,
+        "credentials": {
+          "username": "admin",
+          "password": "secret"
+        },
+        "options": {
+          "ssl": true,
+          "pool": {
+            "max": 20,
+            "min": 5,
+            "idleTimeout": 30000
+          }
+        }
+      },
+      "replica": {
+        "host": "replica.local",
+        "port": 5432
+      }
+    }
+  }
+}
+```
+
+```typescript
+const DatabaseConfig = () => {
+  const config = useConfig('complex');
+  
+  // Accès aux chemins profonds
+  const primaryHost = config.get('database.connections.primary.host');
+  const poolMax = config.get('database.connections.primary.options.pool.max');
+  const sslEnabled = config.get('database.connections.primary.options.ssl');
+  
+  // Utilisation avec tableau de chemin
+  const credentials = config.get(['database', 'connections', 'primary', 'credentials']);
+  
+  return (
+    <div>
+      <h3>Database Configuration</h3>
+      <p>Primary Host: {primaryHost}</p>
+      <p>Max Pool Connections: {poolMax}</p>
+      <p>SSL: {sslEnabled ? 'Enabled' : 'Disabled'}</p>
+      <pre>{JSON.stringify(credentials, null, 2)}</pre>
+    </div>
+  );
+};
+```
+
+## 🎯 Exemples Complets
+
+### Exemple 1 : Configuration d'API avec fallback
+
+```typescript
+import { useConfig } from '@arc-js/config-manager';
+
+const ApiClient = () => {
+  const config = useConfig();
+  
+  const getApiConfig = () => {
+    // Utiliser l'URL de l'ENV si disponible, sinon la config globale
+    const baseUrl = config.getEnv('apiUrl') || 
+                   config.get('api.baseUrl', { 
+                     defaultValue: 'http://localhost:3000' 
+                   });
+    
+    const timeout = config.get('api.timeout', { defaultValue: 30000 });
+    const retryAttempts = config.get('api.retryAttempts', { defaultValue: 3 });
+    
+    return { baseUrl, timeout, retryAttempts };
+  };
+  
+  const fetchData = async () => {
+    const { baseUrl, timeout } = getApiConfig();
+    
+    try {
+      const response = await fetch(`\${baseUrl}/data`, {
+        timeout,
+        headers: {
+          'Content-Type': 'application/json'
+        }
+      });
+      
+      return await response.json();
+    } catch (error) {
+      console.error('API Error:', error);
+      throw error;
+    }
+  };
+  
+  return (
+    <div>
+      <button onClick={fetchData}>
+        Fetch Data
+      </button>
+    </div>
+  );
+};
+```
+
+### Exemple 2 : Feature flags modulaires
+
+```typescript
+import { useConfigValue } from '@arc-js/config-manager';
+
+const FeatureComponent = ({ featureName, moduleName }: { 
+  featureName: string, 
+  moduleName?: string 
+}) => {
+  const { value: isEnabled, isLoading } = useConfigValue<boolean>(
+    `features.\${featureName}`,
+    { 
+      moduleName,
+      defaultValue: false 
+    }
+  );
+  
+  if (isLoading) return <div>Loading feature...</div>;
+  if (!isEnabled) return null;
+  
+  return (
+    <div className={`feature \${featureName}`}>
+      <h3>Feature: {featureName}</h3>
+      {/* Contenu de la feature */}
+    </div>
+  );
+};
+
+// Utilisation
+const AppFeatures = () => {
+  return (
+    <div>
+      <FeatureComponent featureName="analytics" moduleName="admin" />
+      <FeatureComponent featureName="darkMode" />
+      <FeatureComponent featureName="experimental" moduleName="dashboard" />
+    </div>
+  );
+};
+```
+
+### Exemple 3 : Configuration dynamique avec React Query
+
+```typescript
+import { useQuery } from '@tanstack/react-query';
+import { useConfig } from '@arc-js/config-manager';
+
+const ConfigBasedQuery = () => {
+  const config = useConfig('admin');
+  
+  const { data, isLoading, error } = useQuery({
+    queryKey: ['users', 'list'],
+    queryFn: async () => {
+      const baseUrl = config.getOrThrow('api.baseUrl');
+      const pageSize = config.get('pagination.pageSize', { defaultValue: 20 });
+      
+      const response = await fetch(
+        `\${baseUrl}/users?limit=\${pageSize}`
+      );
+      
+      if (!response.ok) throw new Error('Failed to fetch');
+      return response.json();
+    },
+    // Utiliser la config pour les options de requête
+    retry: config.get('api.retryAttempts', { defaultValue: 3 }),
+    retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
+    enabled: config.get('features.dataFetching', { defaultValue: true })
+  });
+  
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  
+  return (
+    <div>
+      <h2>Users</h2>
+      <ul>
+        {data?.users?.map(user => (
+          <li key={user.id}>{user.name}</li>
+        ))}
+      </ul>
+    </div>
+  );
+};
+```
+
+## 🔧 Configuration Avancée
+
+### Configuration Vite
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  define: {
+    // Exposer les variables d'environnement
+    'import.meta.env': process.env
+  }
+});
+```
+
+### Configuration TypeScript
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["DOM", "DOM.Iterable", "ES2020"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src", "node_modules/@arc-js/config-manager/**/*"]
+}
+```
+
+### Scripts de validation
+
+```json
+{
+  "scripts": {
+    "validate-config": "node scripts/validate-config.js",
+    "generate-config-schema": "node scripts/generate-schema.js",
+    "check-env": "node scripts/check-environment.js"
+  }
+}
+```
+
+## 📋 Table des Conventions
+
+### Chemins de configuration
+
+| Type | Format | Exemple |
+|------|--------|---------|
+| Pointé | `parent.child.grandchild` | `app.features.analytics` |
+| Tableau | `['parent', 'child', 'grandchild']` | `['api', 'baseUrl']` |
+| Mixte | Supporté | `app.features[0].name` |
+
+### Fichiers de configuration
+
+| Chemin | Portée | Priorité |
+|--------|--------|----------|
+| `src/config.json` | Globale | Base |
+| `src/modules/*/config.json` | Module | Écrase la globale |
+| `.env` / Variables | Environnement | Écrase tout |
+
+### Variables d'environnement
+
+| Variable | Conversion | Accès |
+|----------|------------|-------|
+| `VITE_API_URL` | `apiUrl` | `config.getEnv('apiUrl')` |
+| `VITE_APP_NAME` | `appName` | `config.get('appName', {moduleName: 'ENV'})` |
+| `NODE_ENV` | `nodeEnv` | `config.getEnv('NODE_ENV')` |
+
+## 🛡️ Gestion des Erreurs
+
+### Fallback et validation
+
+```typescript
+const SafeConfigAccess = () => {
+  const config = useConfig();
+  
+  try {
+    // Cette méthode lève une exception si le chemin n'existe pas
+    const requiredValue = config.getOrThrow('required.path', 'admin');
+    
+    return (
+      <div>
+        <p>Value: {requiredValue}</p>
+      </div>
+    );
+  } catch (error) {
+    return (
+      <div className="error">
+        <p>Configuration error: {(error as Error).message}</p>
+        <p>Using fallback configuration...</p>
+      </div>
+    );
+  }
+};
+```
+
+### Logs en développement
+
+```typescript
+// Le service loggue automatiquement en mode développement
+const DebugConfig = () => {
+  const config = useConfig();
+  const isDev = config.isDevelopment();
+  
+  if (isDev) {
+    // Afficher toute la configuration en dev
+    console.log('Current Configuration:', config.getAll());
+    
+    // Vérifier les chemins manquants
+    const missingPaths = ['app.name', 'api.baseUrl', 'unknown.path'];
+    missingPaths.forEach(path => {
+      if (!config.has(path)) {
+        console.warn(`Missing config path: \${path}`);
+      }
+    });
+  }
+  
+  return null;
+};
+```
+
+## 📄 Licence
+
+MIT License - Voir le fichier [LICENSE](LICENSE) pour plus de détails.
+
+## 🐛 Signaler un Bug
+
+Envoyez-nous un mail à l'adresse `contact.inicode@gmail.com` pour :
+- Signaler un bug
+- Proposer une amélioration
+- Poser une question sur l'utilisation
+- Demander une nouvelle fonctionnalité
+
+---
+
+**@arc-js/config-manager** - Le système de configuration modulaire pour React et TypeScript.
+
+*Développé par l'équipe INICODE*

package/config.d.ts

@@ -0,0 +1,13 @@
+declare const DEFAULT_LOCALE = "en";
+declare const SUPPORTED_LOCALES: string[];
+declare const COOKIE_NAME = "app_locale";
+type Locale = typeof SUPPORTED_LOCALES[number];
+declare const getSavedLocale: (supportedLocales?: string[]) => string;
+declare const saveLocale: (locale: string) => void;
+declare const PATH_CONFIG: {
+    SRC_DIR: string;
+};
+declare const SRC_DIR: string;
+
+export { COOKIE_NAME, DEFAULT_LOCALE, PATH_CONFIG, SRC_DIR, SUPPORTED_LOCALES, getSavedLocale, saveLocale };
+export type { Locale };