@fulmenhq/tsfulmen 0.2.0 → 0.2.3

package/dist/config/index.d.ts

@@ -1,3 +1,33 @@
+/**
+ * Environment variable alias utilities.
+ *
+ * Workhorse templates sometimes support both canonical nested env vars and
+ * convenience aliases (e.g. TUVAN_SERVER_PORT vs TUVAN_PORT).
+ *
+ * This helper standardizes alias resolution and conflict reporting.
+ */
+interface EnvAliasConflict {
+    canonicalKey: string;
+    aliasKey: string;
+    canonicalValue: string;
+    aliasValue: string;
+}
+interface ResolveEnvAliasesResult {
+    env: Record<string, string | undefined>;
+    applied: Array<{
+        aliasKey: string;
+        canonicalKey: string;
+    }>;
+    conflicts: EnvAliasConflict[];
+}
+/**
+ * Resolve env var aliases into canonical keys.
+ *
+ * - If canonical key is unset and alias is set, the alias value is copied to canonical.
+ * - If both are set and differ, a conflict is recorded (canonical is left unchanged).
+ */
+declare function resolveEnvAliases(env: Record<string, string | undefined>, aliasToCanonical: Record<string, string>): ResolveEnvAliasesResult;
+
 /**
  * Config Path API errors - implements Fulmen Config Path Standard error handling
  */
@@ -119,6 +149,13 @@ interface LoadConfigOptions {
      * Defaults to identity.app.config_name or identity.app
      */
     userConfigName?: string;
+    /**
+     * Include env var consumption metadata for diagnostics.
+     *
+     * When enabled, loadConfig() records which environment variable keys were
+     * consumed for prefix-based overrides.
+     */
+    includeEnvVarReport?: boolean;
 }
 /**
  * Metadata about the loaded configuration
@@ -136,6 +173,14 @@ interface ConfigMetadata {
      * Environment variable prefix used for overrides
      */
     envPrefix: string;
+    /**
+     * Environment variable keys consumed (only when includeEnvVarReport is enabled)
+     */
+    envVarsConsumed?: string[];
+    /**
+     * Count of environment variable keys consumed (only when includeEnvVarReport is enabled)
+     */
+    envVarsConsumedCount?: number;
     /**
      * List of active configuration layers ("defaults", "user", "env")
      */
@@ -232,4 +277,4 @@ declare function resolveConfigPath(filename: string, searchPaths: string[], opti
  */
 declare const VERSION = "0.1.0";
 
-export { type AppIdentifier, type ConfigMetadata, ConfigPathError, type ConfigPathOptions, ConfigValidationError, type LoadConfigOptions, type LoadedConfig, type PlatformDirs, VERSION, type XDGBaseDirs, ensureDirExists, getAppCacheDir, getAppConfigDir, getAppDataDir, getConfigSearchPaths, getFulmenCacheDir, getFulmenConfigDir, getFulmenDataDir, getXDGBaseDirs, loadConfig, resolveConfigPath };
+export { type AppIdentifier, type ConfigMetadata, ConfigPathError, type ConfigPathOptions, ConfigValidationError, type EnvAliasConflict, type LoadConfigOptions, type LoadedConfig, type PlatformDirs, type ResolveEnvAliasesResult, VERSION, type XDGBaseDirs, ensureDirExists, getAppCacheDir, getAppConfigDir, getAppDataDir, getConfigSearchPaths, getFulmenCacheDir, getFulmenConfigDir, getFulmenDataDir, getXDGBaseDirs, loadConfig, resolveConfigPath, resolveEnvAliases };