# @mostajs/config — fiche LLM
> Chargeur de variables d'environnement avec cascade de profils MOSTA_ENV — un seul .env, plusieurs profils, fallback silencieux.

- Version: 1.1.0 · Licence: AGPL-3.0-or-later · Auteur: Dr Hamid MADANI <drmdh@msn.com>
- Chemin: mostajs/mosta-config · Statut audit: complet (dist/)
- Nouveau en 1.1.0 : `loadEnv()` / `parseEnv()` — LECTURE du fichier .env intégrée, ZÉRO dépendance (plus besoin de dotenv).

## RÔLE
Lit les variables d'environnement avec une cascade de résolution pilotée par un unique
MOSTA_ENV. Un seul fichier .env contient les valeurs par défaut plus des surcharges
préfixées par profil (TEST, DEV, STAGING, PROD). Évite la multiplication des .env.test /
.env.development / .env.production et leur désynchronisation. Ne lève jamais d'exception :
sur clé absente, retombe silencieusement sur la variable simple puis sur le fallback.

## INSTALLATION
npm i @mostajs/config

## EXPORTS
- getEnv — lecture string
- getEnvBool — lecture booléenne
- getEnvNumber — lecture numérique
- getCurrentProfile — nom du profil actif
- loadEnv — CHARGE un fichier .env dans process.env (zéro-dép) — 1.1.0
- parseEnv — parse un contenu .env en objet (sans toucher process.env) — 1.1.0

## API — SIGNATURES
- getEnv(key: string, fallback: string): string
- getEnv(key: string, fallback?: undefined): string | undefined
  // le type de retour se rétrécit à `string` quand un fallback string est fourni
- getEnvBool(key: string, fallback?: boolean): boolean
  // true uniquement si la valeur résolue vaut littéralement 'true' (insensible à la casse, trimmé)
- getEnvNumber(key: string, fallback: number): number
- getEnvNumber(key: string, fallback?: undefined): number | undefined
  // retourne fallback si la valeur est absente ou n'est pas un nombre fini
- getCurrentProfile(): string | undefined  // nom du profil actif (trimmé) ou undefined
- loadEnv(options?: LoadEnvOptions): LoadEnvResult
  // lit+parse <cwd>/.env (ou options.path) puis peuple process.env ; ne lève jamais si le fichier est absent
  // (retourne { loaded:false }) ; par défaut ne SURCHARGE pas les clés déjà présentes (override:true pour forcer)
- parseEnv(content: string): Record<string, string>
  // parse pur (aucun effet de bord) : lignes vides/#, préfixe `export`, valeurs entre '..'/".." (échappements \n \t \r \" \\),
  // commentaire inline ` #...` sur valeur non-quotée (un # collé est gardé : URL/JSON/hash saufs)

## TYPES CLÉS
- LoadEnvOptions { path?: string; override?: boolean; encoding?: BufferEncoding }
  // path défaut = <cwd>/.env ; override défaut = false ; encoding défaut = 'utf8'
- LoadEnvResult { parsed: Record<string,string>; loaded: boolean; path: string }

## PATTERN
```ts
import { getEnv, getEnvBool, getEnvNumber, getCurrentProfile } from '@mostajs/config';

const dialect  = getEnv('DB_DIALECT', 'sqlite');   // string garanti
const showSql  = getEnvBool('DB_SHOW_SQL', false);
const poolSize = getEnvNumber('DB_POOL_SIZE', 10);
console.log(`Profil: ${getCurrentProfile() ?? 'none'}`);
```
Chargement autonome du .env (1.1.0, sans dotenv) :
```ts
import { loadEnv, getEnvNumber } from '@mostajs/config';
loadEnv();                                  // <cwd>/.env → process.env
loadEnv({ path: '/etc/app/.env', override: true });
const port = getEnvNumber('PORT', 3000);
```
Fichier .env :
```
MOSTA_ENV=TEST
DB_DIALECT=sqlite
DEV_DB_DIALECT=postgres
PROD_DB_DIALECT=mongodb
```

## CASCADE DE RÉSOLUTION (première valeur non-vide gagne)
1. `${MOSTA_ENV}_${key}` — clé préfixée par profil (si MOSTA_ENV défini et non vide)
2. `${key}` — variable simple
3. `fallback` — argument par défaut
4. `undefined` — rien trouvé, pas de défaut

## DÉPEND DE
Aucun module @mostajs/*. Aucune dépendance runtime (uniquement `node:fs`/`node:path` intégrés + devDependencies). Node >= 18.

## PIÈGES
- Une chaîne vide ('') est traitée comme « non défini » : une surcharge profil vide retombe sur la variable simple, jamais sur ''.
- MOSTA_ENV est trimmé : `MOSTA_ENV=  TEST` résout vers le profil `TEST`.
- `getEnv*` LIT process.env (cascade profil) ; il ne lit PAS de fichier. Depuis 1.1.0, appeler `loadEnv()` UNE FOIS au démarrage pour peupler process.env depuis le .env, PUIS lire via getEnv* (dotenv n'est plus nécessaire).
- `loadEnv()` ne SURCHARGE pas par défaut les variables déjà dans l'environnement (l'env réel prime sur le fichier) — passer `override:true` pour l'inverse.
- getEnvBool ne reconnaît QUE 'true' comme vrai ; '1', 'yes', 'on' renvoient false.
- Nommage attendu : profil en MAJUSCULES, variable en UPPER_SNAKE_CASE, clé profilée = `{PROFIL}_{VARIABLE}` (séparateur underscore, jamais le point).

## RÉFÉRENCES
- README.md (cascade, exemples, garantie de fallback silencieux)
- test-scripts/test-env-profile.mjs (cascade de profils, 31 assertions)
- test-scripts/test-loadenv.mjs (loadEnv/parseEnv, 14 assertions)
- LICENSE
