envapt 8.0.0-next.0 → 8.0.0-next.1

package/dist/portable/engine/TemplateResolver.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"TemplateResolver.mjs","names":[],"sources":["../../../src/engine/TemplateResolver.ts"],"sourcesContent":["import { state } from '../core/state';\nimport { debugWarn } from '../infra/Debug';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { EnvapterService } from '../types/Env';\n\n/**\n * Resolve `${VAR}` template references in environment values, guarding against circular\n * references and missing variables.\n * @internal\n */\nexport class TemplateResolver {\n    private readonly TEMPLATE_REGEX = /\\${\\w*}/g;\n\n    constructor(private readonly envService: EnvapterService) {}\n\n    resolveTemplate(key: string, value: string, stack: Set<string> = new Set<string>()): string {\n        stack.add(key);\n        const strict = state.strict;\n\n        const out = value.replace(this.TEMPLATE_REGEX, (template) => {\n            const variable = template.slice(2, -1);\n\n            if (stack.has(variable)) return template; // cycle, preserve\n\n            const raw = this.envService.getRaw(variable);\n            const isMissing = raw === undefined || raw === '' || (strict && raw.trim() === '');\n            if (isMissing) {\n                if (strict) {\n                    throw new EnvaptError(\n                        EnvaptErrorCodes.MissingEnvValue,\n                        `Cannot resolve template variable \"\\${${variable}}\": value is missing or empty.`\n                    );\n                }\n                debugWarn(`unresolved template \\${${variable}} preserved as literal`);\n                return template; // missing or empty, preserve\n            }\n\n            const resolved = this.resolveTemplate(variable, raw, new Set(stack));\n\n            // If resolution still references the current key, skip replacement (indirect cycle)\n            if (resolved.includes(`\\${${key}}`)) return template;\n\n            // If nothing changed (unresolved placeholders stayed), also preserve original template\n            if (resolved === raw && /\\$\\{[^}]*\\}/.test(resolved)) return template;\n\n            return resolved;\n        });\n\n        stack.delete(key);\n        return out;\n    }\n}\n"],"mappings":"0IAWA,IAAa,EAAb,KAA8B,CAGG,WAF7B,eAAkC,WAElC,YAAY,EAA8C,CAA7B,KAAA,WAAA,CAA8B,CAE3D,gBAAgB,EAAa,EAAe,EAAqB,IAAI,IAAuB,CACxF,EAAM,IAAI,CAAG,EACb,IAAM,EAAS,EAAM,OAEf,EAAM,EAAM,QAAQ,KAAK,eAAiB,GAAa,CACzD,IAAM,EAAW,EAAS,MAAM,EAAG,EAAE,EAErC,GAAI,EAAM,IAAI,CAAQ,EAAG,OAAO,EAEhC,IAAM,EAAM,KAAK,WAAW,OAAO,CAAQ,EAE3C,GADkB,IAAQ,IAAA,IAAa,IAAQ,IAAO,GAAU,EAAI,KAAK,IAAM,GAChE,CACX,GAAI,EACA,MAAM,IAAI,EAAA,IAEN,wCAAwC,EAAS,+BACrD,EAGJ,OADA,EAAU,0BAA0B,EAAS,uBAAuB,EAC7D,CACX,CAEA,IAAM,EAAW,KAAK,gBAAgB,EAAU,EAAK,IAAI,IAAI,CAAK,CAAC,EAQnE,OALI,EAAS,SAAS,MAAM,EAAI,EAAE,GAG9B,IAAa,GAAO,cAAc,KAAK,CAAQ,EAAU,EAEtD,CACX,CAAC,EAGD,OADA,EAAM,OAAO,CAAG,EACT,CACX,CACJ"}
+{"version":3,"file":"TemplateResolver.mjs","names":[],"sources":["../../../src/engine/TemplateResolver.ts"],"sourcesContent":["import { isMissing } from '../core/missing';\nimport { state } from '../core/state';\nimport { debugWarn } from '../infra/Debug';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { EnvapterService } from '../types/Env';\n\n/**\n * Resolve `${VAR}` template references in environment values, guarding against circular\n * references and missing variables.\n * @internal\n */\nexport class TemplateResolver {\n    private readonly TEMPLATE_REGEX = /\\${\\w*}/g;\n\n    constructor(private readonly envService: EnvapterService) {}\n\n    resolveTemplate(key: string, value: string, stack: Set<string> = new Set<string>()): string {\n        stack.add(key);\n        const strict = state.strict;\n\n        const out = value.replace(this.TEMPLATE_REGEX, (template) => {\n            const variable = template.slice(2, -1);\n\n            if (stack.has(variable)) return template; // cycle, preserve\n\n            const raw = this.envService.getRaw(variable);\n            if (raw === undefined || isMissing(raw)) {\n                if (strict) {\n                    throw new EnvaptError(\n                        EnvaptErrorCodes.MissingEnvValue,\n                        `Cannot resolve template variable \"\\${${variable}}\": value is missing or empty.`\n                    );\n                }\n                debugWarn(`unresolved template \\${${variable}} preserved as literal`);\n                return template; // missing or empty, preserve\n            }\n\n            const resolved = this.resolveTemplate(variable, raw, new Set(stack));\n\n            // If resolution still references the current key, skip replacement (indirect cycle)\n            if (resolved.includes(`\\${${key}}`)) return template;\n\n            // If nothing changed (unresolved placeholders stayed), also preserve original template\n            if (resolved === raw && /\\$\\{[^}]*\\}/.test(resolved)) return template;\n\n            return resolved;\n        });\n\n        stack.delete(key);\n        return out;\n    }\n}\n"],"mappings":"0LAYA,IAAa,EAAb,KAA8B,CAGG,WAF7B,eAAkC,WAElC,YAAY,EAA8C,CAA7B,KAAA,WAAA,CAA8B,CAE3D,gBAAgB,EAAa,EAAe,EAAqB,IAAI,IAAuB,CACxF,EAAM,IAAI,CAAG,EACb,IAAM,EAAS,EAAM,OAEf,EAAM,EAAM,QAAQ,KAAK,eAAiB,GAAa,CACzD,IAAM,EAAW,EAAS,MAAM,EAAG,EAAE,EAErC,GAAI,EAAM,IAAI,CAAQ,EAAG,OAAO,EAEhC,IAAM,EAAM,KAAK,WAAW,OAAO,CAAQ,EAC3C,GAAI,IAAQ,IAAA,IAAa,EAAU,CAAG,EAAG,CACrC,GAAI,EACA,MAAM,IAAI,EAAA,IAEN,wCAAwC,EAAS,+BACrD,EAGJ,OADA,EAAU,0BAA0B,EAAS,uBAAuB,EAC7D,CACX,CAEA,IAAM,EAAW,KAAK,gBAAgB,EAAU,EAAK,IAAI,IAAI,CAAK,CAAC,EAQnE,OALI,EAAS,SAAS,MAAM,EAAI,EAAE,GAG9B,IAAa,GAAO,cAAc,KAAK,CAAQ,EAAU,EAEtD,CACX,CAAC,EAGD,OADA,EAAM,OAAO,CAAG,EACT,CACX,CACJ"}

package/dist/portable/engine/Validators.mjs

@@ -1,2 +1,2 @@
-import{isArrayOf as e}from"../converters/Converters.mjs";import{EnvaptError as t}from"../infra/Error.mjs";import{BuiltInConverterTypeCheckers as n,ListOfBuiltInConverters as r}from"../converters/ListOfBuiltInConverters.mjs";var i=class{static isBuiltInConverter(e){return typeof e==`string`?r.includes(e):!1}static isArrayConverter(t){return e(t)}static isStandardSchema(e){if(typeof e!=`object`||!e||!(`~standard`in e))return!1;let t=e[`~standard`];if(typeof t!=`object`||!t)return!1;let n=t;return n.version===1&&typeof n.validate==`function`}static customConvertor(e){if(typeof e!=`function`)throw new t(203,`Custom converter must be a function, got ${typeof e}.`)}static arrayConverter(n){if(!e(n))throw new t(201,`Expected an ArrayOf<...> token produced by Converters.array(...)`);if(typeof n.delimiter!=`string`||n.delimiter.length===0)throw new t(301,`ArrayOf<...> requires a non-empty string delimiter, got ${typeof n.delimiter}`);let i=n.of;if(!(typeof i==`string`&&r.includes(i))&&typeof i!=`function`)throw new t(201,`ArrayOf<...> element ("of") must be a built-in scalar token or a function, got ${typeof i}`)}static builtInConverter(e){if(typeof e!=`string`)throw new t(204,`Expected string, got ${typeof e}`);if(!r.includes(e))throw new t(202,`"${e}" is not a valid converter type. Valid types are: ${r.join(`,`)}`)}static validateBuiltInConverterFallback(e,r){let i=n[e];if(!i(r))throw new t(104,`Fallback type does not match converter "${e}". Expected ${e} compatible type.`)}static validateArrayFallbackElementTypes(e){if(e.length===0)return;let n=typeof e[0];if(e.some((e,t)=>t===0?!1:typeof e!==n))throw new t(103,`All elements in array fallback must have the same type. Found mixed types.`)}static validateArrayConverterElementTypeMatch(e,r){if(r.length===0||typeof e==`function`)return;let i=e;if(i===`time`){let e=r.every(e=>typeof e==`number`),n=r.every(e=>typeof e==`string`);if(!e&&!n)throw new t(103,`Time array fallback must be all numbers or all time-string entries.`);return}let a=n[i],o=r[0];if(!a(o))throw new t(103,`Array converter type "${i}" does not match fallback element type. Expected ${i} compatible elements.`)}static isPrimitiveConstructor(e){return e===String||e===Number||e===Boolean||e===BigInt||e===Symbol}static coercePrimitiveFallback(e,t){return this.isCorrectPrimitiveType(e,t)?t:this.performPrimitiveCoercion(e,t)}static isCorrectPrimitiveType(e,t){return e===String&&typeof t==`string`||e===Number&&typeof t==`number`||e===Boolean&&typeof t==`boolean`||e===BigInt&&typeof t==`bigint`||e===Symbol&&typeof t==`symbol`}static performPrimitiveCoercion(e,n){try{if(e===String)return String(n);if(e===Number)return Number(n);if(e===Boolean)return!!n;if(e===BigInt)return BigInt(n);if(e===Symbol)return Symbol.for(String(n))}catch(n){throw new t(205,`Failed to coerce fallback value using ${e.name}: ${n.message}`)}throw new t(205,`Unknown primitive converter: ${e.name}`)}static validateSyncProcessEnv(e){if(typeof e!=`boolean`)throw new t(302,`Envapter.syncProcessEnv must be a boolean, got ${typeof e}.`)}static validateFileApiMode(e){if(e!==`warn`&&e!==`throw`)throw new t(302,`Envapter.fileApiMode must be 'warn' or 'throw', got ${typeof e==`string`?`'${e}'`:typeof e}.`)}static validateEnvFileOptions(e){let n=new Set([`encoding`,`override`]),r=Object.keys(e).filter(e=>!n.has(e));if(r.length>0)throw new t(302,`Invalid envFileOptions: ${r.join(`, `)}. Allowed options: ${Array.from(n).join(`, `)}. For debug output, use Envapter.debug or the ENVAPT_DEBUG env var.`);return!0}static validateEnvFilesExist(e,n){let r=e.filter(e=>!n(e));if(r.length>0)throw new t(303,`Environment file not found at path: ${r.join(`, `)}`)}};export{i as Validator};
+import{EnvaptError as e}from"../infra/Error.mjs";import{isArrayOf as t}from"../converters/Converters.mjs";import{BuiltInConverterTypeCheckers as n,ListOfBuiltInConverters as r}from"../converters/ListOfBuiltInConverters.mjs";var i=class{static isBuiltInConverter(e){return typeof e==`string`?r.includes(e):!1}static isArrayConverter(e){return t(e)}static isStandardSchema(e){if(typeof e!=`object`||!e||!(`~standard`in e))return!1;let t=e[`~standard`];if(typeof t!=`object`||!t)return!1;let n=t;return n.version===1&&typeof n.validate==`function`}static customConvertor(t){if(typeof t!=`function`)throw new e(203,`Custom converter must be a function, got ${typeof t}.`)}static arrayConverter(n){if(!t(n))throw new e(201,`Expected an ArrayOf<...> token produced by Converters.array(...)`);if(typeof n.delimiter!=`string`||n.delimiter.length===0)throw new e(301,`ArrayOf<...> requires a non-empty string delimiter, got ${typeof n.delimiter}`);let i=n.of;if(!(typeof i==`string`&&r.includes(i))&&typeof i!=`function`)throw new e(201,`ArrayOf<...> element ("of") must be a built-in scalar token or a function, got ${typeof i}`)}static builtInConverter(t){if(typeof t!=`string`)throw new e(204,`Expected string, got ${typeof t}`);if(!r.includes(t))throw new e(202,`"${t}" is not a valid converter type. Valid types are: ${r.join(`,`)}`)}static validateBuiltInConverterFallback(t,r){let i=n[t];if(!i(r))throw new e(104,`Fallback type does not match converter "${t}". Expected ${t} compatible type.`)}static validateArrayFallbackElementTypes(t){if(t.length===0)return;let n=typeof t[0];if(t.some((e,t)=>t===0?!1:typeof e!==n))throw new e(103,`All elements in array fallback must have the same type. Found mixed types.`)}static validateArrayConverterElementTypeMatch(t,r){if(r.length===0||typeof t==`function`)return;let i=t;if(i===`time`){let t=r.every(e=>typeof e==`number`),n=r.every(e=>typeof e==`string`);if(!t&&!n)throw new e(103,`Time array fallback must be all numbers or all time-string entries.`);return}let a=n[i],o=r[0];if(!a(o))throw new e(103,`Array converter type "${i}" does not match fallback element type. Expected ${i} compatible elements.`)}static isPrimitiveConstructor(e){return e===String||e===Number||e===Boolean||e===BigInt||e===Symbol}static coercePrimitiveFallback(e,t){return this.isCorrectPrimitiveType(e,t)?t:this.performPrimitiveCoercion(e,t)}static isCorrectPrimitiveType(e,t){return e===String&&typeof t==`string`||e===Number&&typeof t==`number`||e===Boolean&&typeof t==`boolean`||e===BigInt&&typeof t==`bigint`||e===Symbol&&typeof t==`symbol`}static performPrimitiveCoercion(t,n){try{if(t===String)return String(n);if(t===Number)return Number(n);if(t===Boolean)return!!n;if(t===BigInt)return BigInt(n);if(t===Symbol)return Symbol.for(String(n))}catch(n){throw new e(205,`Failed to coerce fallback value using ${t.name}: ${n.message}`)}throw new e(205,`Unknown primitive converter: ${t.name}`)}static validateSyncProcessEnv(t){if(typeof t!=`boolean`)throw new e(302,`Envapter.syncProcessEnv must be a boolean, got ${typeof t}.`)}static validateFileApiMode(t){if(t!==`warn`&&t!==`throw`)throw new e(302,`Envapter.fileApiMode must be 'warn' or 'throw', got ${typeof t==`string`?`'${t}'`:typeof t}.`)}static validateEnvFileOptions(t){let n=new Set([`encoding`,`override`]),r=Object.keys(t).filter(e=>!n.has(e));if(r.length>0)throw new e(302,`Invalid envFileOptions: ${r.join(`, `)}. Allowed options: ${Array.from(n).join(`, `)}. For debug output, use Envapter.debug or the ENVAPT_DEBUG env var.`);return!0}static validateEnvFilesExist(t,n){let r=t.filter(e=>!n(e));if(r.length>0)throw new e(303,`Environment file not found at path: ${r.join(`, `)}`)}};export{i as Validator};
 //# sourceMappingURL=Validators.mjs.map

package/dist/portable/index.mjs

@@ -1 +1 @@
-import{Environment as e}from"./core/Environment.mjs";import{Converters as t,isArrayOf as n}from"./converters/Converters.mjs";import{EnvaptError as r,EnvaptErrorCodes as i}from"./infra/Error.mjs";import{PortableSource as a}from"./sources/PortableSource.mjs";import{merge as o}from"./sources/merge.mjs";import{Envapt as s}from"./decorators/modern/Envapt.mjs";import{EnvBool as c,EnvNum as l,EnvStr as u,EnvTime as d,EnvUrl as f}from"./decorators/modern/SugarDecorators.mjs";import{PortableEnvapter as p}from"./engine/PortableEnvapter.mjs";export{t as Converters,c as EnvBool,l as EnvNum,u as EnvStr,d as EnvTime,f as EnvUrl,s as Envapt,r as EnvaptError,i as EnvaptErrorCodes,p as Envapter,e as Environment,a as PortableSource,n as isArrayOf,o as merge};
+import{EnvaptError as e,EnvaptErrorCodes as t}from"./infra/Error.mjs";import{Environment as n}from"./core/Environment.mjs";import{Converters as r}from"./converters/Converters.mjs";import{PortableSource as i}from"./sources/PortableSource.mjs";import{merge as a}from"./sources/merge.mjs";import{Envapt as o}from"./decorators/modern/Envapt.mjs";import{EnvBool as s,EnvNum as c,EnvStr as l,EnvTime as u,EnvUrl as d}from"./decorators/modern/SugarDecorators.mjs";import{PortableEnvapter as f}from"./engine/PortableEnvapter.mjs";export{r as Converters,s as EnvBool,c as EnvNum,l as EnvStr,u as EnvTime,d as EnvUrl,o as Envapt,e as EnvaptError,t as EnvaptErrorCodes,f as Envapter,n as Environment,i as PortableSource,a as merge};

package/dist/portable/infra/Debug.mjs

@@ -1,2 +1,2 @@
-import{EnvaptError as e}from"./Error.mjs";import{readRuntimeEnv as t,writeRuntimeLine as n}from"./runtime.mjs";const r=new Set([`silent`,`warn`,`verbose`]);let i=`silent`,a=!1;function o(e){return e!==void 0&&r.has(e)}function s(){if(!a){let e=t().ENVAPT_DEBUG;i=o(e)?e:`silent`,a=!0}return i}function c(t){if(!o(t))throw new e(302,`Invalid debug level "${String(t)}". Expected 'silent' | 'warn' | 'verbose'.`);i=t,a=!0}function l(){return s()}function u(e){let t=s();(t===`warn`||t===`verbose`)&&n(`[envapt] ${e}`)}function d(e){s()===`verbose`&&n(`[envapt] ${e}`)}export{d as debugVerbose,u as debugWarn,l as getDebugLevel,c as setDebugLevel};
+import{EnvaptError as e}from"./Error.mjs";import{readRuntimeVar as t,writeRuntimeLine as n}from"./runtime.mjs";const r=new Set([`silent`,`warn`,`verbose`]);let i=`silent`,a=!1;function o(e){return e!==void 0&&r.has(e)}function s(){if(!a){let e=t(`ENVAPT_DEBUG`);i=o(e)?e:`silent`,a=!0}return i}function c(t){if(!o(t))throw new e(302,`Invalid debug level "${String(t)}". Expected 'silent' | 'warn' | 'verbose'.`);i=t,a=!0}function l(){return s()}function u(e){let t=s();(t===`warn`||t===`verbose`)&&n(`[envapt] ${e}`)}function d(e){s()===`verbose`&&n(`[envapt] ${e}`)}export{d as debugVerbose,u as debugWarn,l as getDebugLevel,c as setDebugLevel};
 //# sourceMappingURL=Debug.mjs.map

package/dist/portable/infra/Debug.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"Debug.mjs","names":[],"sources":["../../../src/infra/Debug.ts"],"sourcesContent":["import { EnvaptError, EnvaptErrorCodes } from './Error';\nimport { readRuntimeEnv, writeRuntimeLine } from './runtime';\n\n/**\n * Debug log levels for {@link Envapter.debug}. `silent` (default) emits nothing.\n * `warn` covers signals that might indicate misconfiguration, failed file reads,\n * unresolved templates (when not strict), and any read of a missing or empty variable\n * (whether it returns a fallback or `undefined`). `verbose` adds every loaded file,\n * per-file key count, per-key load lines, and effective-paths / cache-rebuild notices.\n * @public\n */\nexport type DebugLevel = 'silent' | 'warn' | 'verbose';\n\nconst VALID_LEVELS: ReadonlySet<string> = new Set<DebugLevel>(['silent', 'warn', 'verbose']);\n\nlet currentLevel: DebugLevel = 'silent';\nlet initialized = false;\n\nfunction isDebugLevel(value: string | undefined): value is DebugLevel {\n    return value !== undefined && VALID_LEVELS.has(value);\n}\n\n// Reads `ENVAPT_DEBUG` lazily on first access. Setter wins after that.\nfunction resolveLevel(): DebugLevel {\n    if (!initialized) {\n        const fromEnv = readRuntimeEnv().ENVAPT_DEBUG;\n        currentLevel = isDebugLevel(fromEnv) ? fromEnv : 'silent';\n        initialized = true;\n    }\n    return currentLevel;\n}\n\n/** @internal */\nexport function setDebugLevel(level: DebugLevel): void {\n    if (!isDebugLevel(level)) {\n        throw new EnvaptError(\n            EnvaptErrorCodes.InvalidUserDefinedConfig,\n            `Invalid debug level \"${String(level)}\". Expected 'silent' | 'warn' | 'verbose'.`\n        );\n    }\n    currentLevel = level;\n    initialized = true;\n}\n\n/** @internal */\nexport function getDebugLevel(): DebugLevel {\n    return resolveLevel();\n}\n\n/** @internal */\nexport function resetDebugForTesting(): void {\n    currentLevel = 'silent';\n    initialized = false;\n}\n\n/** @internal */\nexport function debugWarn(message: string): void {\n    const level = resolveLevel();\n    if (level === 'warn' || level === 'verbose') {\n        writeRuntimeLine(`[envapt] ${message}`);\n    }\n}\n\n/** @internal */\nexport function debugVerbose(message: string): void {\n    if (resolveLevel() === 'verbose') {\n        writeRuntimeLine(`[envapt] ${message}`);\n    }\n}\n"],"mappings":"+GAaA,MAAM,EAAoC,IAAI,IAAgB,CAAC,SAAU,OAAQ,SAAS,CAAC,EAE3F,IAAI,EAA2B,SAC3B,EAAc,GAElB,SAAS,EAAa,EAAgD,CAClE,OAAO,IAAU,IAAA,IAAa,EAAa,IAAI,CAAK,CACxD,CAGA,SAAS,GAA2B,CAChC,GAAI,CAAC,EAAa,CACd,IAAM,EAAU,EAAe,CAAC,CAAC,aACjC,EAAe,EAAa,CAAO,EAAI,EAAU,SACjD,EAAc,EAClB,CACA,OAAO,CACX,CAGA,SAAgB,EAAc,EAAyB,CACnD,GAAI,CAAC,EAAa,CAAK,EACnB,MAAM,IAAI,EAAA,IAEN,wBAAwB,OAAO,CAAK,EAAE,2CAC1C,EAEJ,EAAe,EACf,EAAc,EAClB,CAGA,SAAgB,GAA4B,CACxC,OAAO,EAAa,CACxB,CASA,SAAgB,EAAU,EAAuB,CAC7C,IAAM,EAAQ,EAAa,GACvB,IAAU,QAAU,IAAU,YAC9B,EAAiB,YAAY,GAAS,CAE9C,CAGA,SAAgB,EAAa,EAAuB,CAC5C,EAAa,IAAM,WACnB,EAAiB,YAAY,GAAS,CAE9C"}
+{"version":3,"file":"Debug.mjs","names":[],"sources":["../../../src/infra/Debug.ts"],"sourcesContent":["import { EnvaptError, EnvaptErrorCodes } from './Error';\nimport { readRuntimeVar, writeRuntimeLine } from './runtime';\n\n/**\n * Debug log levels for {@link Envapter.debug}. `silent` (default) emits nothing.\n * `warn` covers signals that might indicate misconfiguration, failed file reads,\n * unresolved templates (when not strict), and any read of a missing or empty variable\n * (whether it returns a fallback or `undefined`). `verbose` adds every loaded file,\n * per-file key count, per-key load lines, and effective-paths / cache-rebuild notices.\n * @public\n * @see {@link https://envapt.materwelon.dev/docs/configuration#debug-logging}\n */\nexport type DebugLevel = 'silent' | 'warn' | 'verbose';\n\nconst VALID_LEVELS: ReadonlySet<string> = new Set<DebugLevel>(['silent', 'warn', 'verbose']);\n\nlet currentLevel: DebugLevel = 'silent';\nlet initialized = false;\n\nfunction isDebugLevel(value: string | undefined): value is DebugLevel {\n    return value !== undefined && VALID_LEVELS.has(value);\n}\n\n// Reads `ENVAPT_DEBUG` lazily on first access. Setter wins after that.\nfunction resolveLevel(): DebugLevel {\n    if (!initialized) {\n        const fromEnv = readRuntimeVar('ENVAPT_DEBUG');\n        currentLevel = isDebugLevel(fromEnv) ? fromEnv : 'silent';\n        initialized = true;\n    }\n    return currentLevel;\n}\n\n/** @internal */\nexport function setDebugLevel(level: DebugLevel): void {\n    if (!isDebugLevel(level)) {\n        throw new EnvaptError(\n            EnvaptErrorCodes.InvalidUserDefinedConfig,\n            `Invalid debug level \"${String(level)}\". Expected 'silent' | 'warn' | 'verbose'.`\n        );\n    }\n    currentLevel = level;\n    initialized = true;\n}\n\n/** @internal */\nexport function getDebugLevel(): DebugLevel {\n    return resolveLevel();\n}\n\n/** @internal */\nexport function resetDebugForTesting(): void {\n    currentLevel = 'silent';\n    initialized = false;\n}\n\n/** @internal */\nexport function debugWarn(message: string): void {\n    const level = resolveLevel();\n    if (level === 'warn' || level === 'verbose') {\n        writeRuntimeLine(`[envapt] ${message}`);\n    }\n}\n\n/** @internal */\nexport function debugVerbose(message: string): void {\n    if (resolveLevel() === 'verbose') {\n        writeRuntimeLine(`[envapt] ${message}`);\n    }\n}\n"],"mappings":"+GAcA,MAAM,EAAoC,IAAI,IAAgB,CAAC,SAAU,OAAQ,SAAS,CAAC,EAE3F,IAAI,EAA2B,SAC3B,EAAc,GAElB,SAAS,EAAa,EAAgD,CAClE,OAAO,IAAU,IAAA,IAAa,EAAa,IAAI,CAAK,CACxD,CAGA,SAAS,GAA2B,CAChC,GAAI,CAAC,EAAa,CACd,IAAM,EAAU,EAAe,cAAc,EAC7C,EAAe,EAAa,CAAO,EAAI,EAAU,SACjD,EAAc,EAClB,CACA,OAAO,CACX,CAGA,SAAgB,EAAc,EAAyB,CACnD,GAAI,CAAC,EAAa,CAAK,EACnB,MAAM,IAAI,EAAA,IAEN,wBAAwB,OAAO,CAAK,EAAE,2CAC1C,EAEJ,EAAe,EACf,EAAc,EAClB,CAGA,SAAgB,GAA4B,CACxC,OAAO,EAAa,CACxB,CASA,SAAgB,EAAU,EAAuB,CAC7C,IAAM,EAAQ,EAAa,GACvB,IAAU,QAAU,IAAU,YAC9B,EAAiB,YAAY,GAAS,CAE9C,CAGA,SAAgB,EAAa,EAAuB,CAC5C,EAAa,IAAM,WACnB,EAAiB,YAAY,GAAS,CAE9C"}

package/dist/portable/infra/Dotenv.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"Dotenv.mjs","names":[],"sources":["../../../src/infra/Dotenv.ts"],"sourcesContent":["import { debugVerbose, debugWarn } from './Debug';\n\n/**\n * Public options for the internal `.env` loader. Mirrors the subset of dotenv's\n * `config()` options that envapt actually supports (no DOTENV_KEY, no quiet).\n * For debug output, use `Envapter.debug` (or the `ENVAPT_DEBUG` env var).\n *\n * @public\n */\nexport interface EnvFileOptions {\n    /** Encoding for reading .env files. Defaults to 'utf8'. */\n    encoding?: string;\n    /** When true, later files override earlier ones (and existing processEnv values). Default false (first-wins). */\n    override?: boolean;\n}\n\n/**\n * Internal call signature used by `EnvapterBase`. The `path` and `processEnv`\n * fields are managed by envapt and never user-supplied.\n * @internal\n */\nexport interface LoadDotenvInput extends EnvFileOptions {\n    path: string | string[];\n    processEnv: Record<string, string>;\n    // Injected so the loader stays free of `node:fs`. Returns `undefined` when the file is absent.\n    readFile(path: string, encoding: string): string | undefined;\n}\n\n// Matches: optional `export`, KEY name, optional whitespace, `=`, optional whitespace, value tail.\n// Multi-line quoted values are handled by re-buffering subsequent lines below.\n// Bounded by anchors with linear-time quantifiers; no catastrophic backtracking risk -- justified\n// eslint-disable-next-line security/detect-unsafe-regex\nconst KEY_LINE_RE = /^\\s*(?:export\\s+)?([A-Za-z_][A-Za-z0-9_]*)\\s*=(.*)$/u;\n\n/**\n * Parse a `.env` text blob into a `Map<string, string>`.\n *\n * Supported syntax:\n * - `KEY=value` and `export KEY=value`\n * - blank lines and full-line `# comments`\n * - single-quoted `'literal'` values (no escape interpretation)\n * - double-quoted `\"value\"` values (interprets `\\n`, `\\r`, `\\t`, `\\\\`, `\\\"`)\n * - backtick-quoted values (literal, like single quotes)\n * - quoted values may span multiple lines\n * - inline `# comment` after an unquoted value (requires whitespace before `#`)\n * - empty values resolve to `\"\"`\n *\n * Mirrors dotenv's quirk where unescaped inner quotes inside a quoted value\n * are tolerated by greedy-matching to the rightmost matching quote on the\n * (possibly multi-line) value buffer. This is what lets a value like\n * `JSON=\"{\"name\":\"x\"}\"` round-trip without escaping.\n *\n * Does NOT perform `${VAR}` expansion — envapt's `Parser` handles that downstream.\n * @internal\n */\nexport function parseDotenv(src: string): Map<string, string> {\n    const out = new Map<string, string>();\n    const lines = src.split(/\\r?\\n/u);\n\n    for (let i = 0; i < lines.length; i++) {\n        const consumed = parseEntry(lines, i);\n        i = consumed.endLine;\n        if (consumed.entry) out.set(consumed.entry.key, consumed.entry.value);\n    }\n\n    return out;\n}\n\ninterface ParsedEntry {\n    key: string;\n    value: string;\n}\n\nfunction parseEntry(lines: string[], start: number): { entry: ParsedEntry | undefined; endLine: number } {\n    /* v8 ignore next -- @preserve caller bounds-checks start so this never falls back */\n    const line = lines[start] ?? '';\n    const trimmedLine = line.trim();\n    if (trimmedLine === '' || trimmedLine.startsWith('#')) return { entry: undefined, endLine: start };\n\n    const match = line.match(KEY_LINE_RE);\n    if (!match) return { entry: undefined, endLine: start };\n\n    const key = match[1] as string;\n    // Drop only leading whitespace before the value; trailing whitespace and inline comments\n    // are dealt with below depending on whether the value is quoted.\n    /* v8 ignore next -- @preserve regex group 2 always matches via `(.*)`, fallback is defensive */\n    const rest = (match[2] ?? '').replace(/^\\s+/u, '');\n    const firstChar = rest[0];\n\n    if (firstChar === '\"' || firstChar === \"'\" || firstChar === '`') {\n        const consumed = consumeQuotedValue(rest, lines, start, firstChar);\n        return { entry: { key, value: consumed.value }, endLine: consumed.endLine };\n    }\n\n    return { entry: { key, value: stripInlineComment(rest) }, endLine: start };\n}\n\nfunction consumeQuotedValue(\n    firstLineRest: string,\n    lines: string[],\n    startLine: number,\n    quote: string\n): { value: string; endLine: number } {\n    let buffer = firstLineRest;\n    let cursor = startLine;\n    let closeIdx = findLastUnescapedQuote(buffer, quote);\n\n    while (closeIdx < 0 && cursor < lines.length - 1) {\n        cursor++;\n        /* v8 ignore next -- @preserve cursor is bounded by the while condition above */\n        buffer += `\\n${lines[cursor] ?? ''}`;\n        closeIdx = findLastUnescapedQuote(buffer, quote);\n    }\n\n    const inner = closeIdx > 0 ? buffer.slice(1, closeIdx) : buffer.slice(1);\n    return { value: quote === '\"' ? unescapeDouble(inner) : inner, endLine: cursor };\n}\n\nfunction stripInlineComment(value: string): string {\n    const hashIdx = findInlineCommentStart(value);\n    const stripped = hashIdx === -1 ? value : value.slice(0, hashIdx);\n    return stripped.trimEnd();\n}\n\nfunction findInlineCommentStart(value: string): number {\n    for (let i = 0; i < value.length; i++) {\n        if (value[i] === '#' && (i === 0 || /\\s/u.test(value[i - 1] as string))) return i;\n    }\n    return -1;\n}\n\n/**\n * Find the rightmost matching closing quote in `buffer` (skipping index 0 which is the\n * opening quote). For `\"`, a quote preceded by an odd number of backslashes is escaped\n * and ignored. Single and backtick quotes do not unescape.\n */\nfunction findLastUnescapedQuote(buffer: string, quote: string): number {\n    for (let i = buffer.length - 1; i > 0; i--) {\n        if (buffer[i] !== quote) continue;\n        if (quote === '\"') {\n            let backslashes = 0;\n            let k = i - 1;\n            while (k >= 0 && buffer[k] === '\\\\') {\n                backslashes++;\n                k--;\n            }\n            if (backslashes % 2 === 1) continue; // escaped\n        }\n        return i;\n    }\n    return -1;\n}\n\nfunction unescapeDouble(raw: string): string {\n    let out = '';\n    for (let i = 0; i < raw.length; i++) {\n        const ch = raw[i];\n        if (ch !== '\\\\' || i === raw.length - 1) {\n            out += ch;\n            continue;\n        }\n        const next = raw[i + 1];\n        i++;\n        switch (next) {\n            case 'n':\n                out += '\\n';\n                break;\n            case 'r':\n                out += '\\r';\n                break;\n            case 't':\n                out += '\\t';\n                break;\n            case '\\\\':\n                out += '\\\\';\n                break;\n            case '\"':\n                out += '\"';\n                break;\n            default:\n                /* v8 ignore next -- @preserve `next` is always defined when this branch is reached (guarded above) */\n                out += `\\\\${next ?? ''}`;\n        }\n    }\n    return out;\n}\n\n/**\n * Load one or more `.env` files into a target `processEnv` map. Mirrors the\n * subset of dotenv's `config()` semantics that envapt depends on: first-wins\n * across multiple paths by default, optional `override: true`, optional\n * non-UTF8 encoding, missing files are skipped silently.\n *\n * Returns the set of keys actually written into `input.processEnv`. Skipped\n * collisions (under default `override: false`) are NOT included.\n * @internal\n */\nexport function loadDotenv(input: LoadDotenvInput): Set<string> {\n    const paths = Array.isArray(input.path) ? input.path : [input.path];\n    const encoding = input.encoding ?? 'utf8';\n    const override = input.override ?? false;\n    const written = new Set<string>();\n\n    for (const filePath of paths) {\n        const src = input.readFile(filePath, encoding);\n        if (src === undefined) {\n            debugWarn(`could not read ${filePath}`);\n            continue;\n        }\n\n        const parsed = parseDotenv(src);\n        debugVerbose(`loaded ${filePath}: ${parsed.size} ${parsed.size === 1 ? 'key' : 'keys'}`);\n        for (const [key, value] of parsed) {\n            const exists = Object.prototype.hasOwnProperty.call(input.processEnv, key);\n            if (!exists || override) {\n                input.processEnv[key] = value;\n                written.add(key);\n                debugVerbose(`${filePath} -> ${key}`);\n            }\n        }\n    }\n\n    return written;\n}\n"],"mappings":"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"}
+{"version":3,"file":"Dotenv.mjs","names":[],"sources":["../../../src/infra/Dotenv.ts"],"sourcesContent":["import { debugVerbose, debugWarn } from './Debug';\n\n/**\n * Public options for the internal `.env` loader. Mirrors the subset of dotenv's\n * `config()` options that envapt actually supports (no DOTENV_KEY, no quiet).\n * For debug output, use `Envapter.debug` (or the `ENVAPT_DEBUG` env var).\n *\n * @public\n * @see {@link https://envapt.materwelon.dev/docs/configuration#which-files-load}\n */\nexport interface EnvFileOptions {\n    /** Encoding for reading .env files. Defaults to 'utf8'. */\n    encoding?: string;\n    /** When true, later files override earlier ones (and existing processEnv values). Default false (first-wins). */\n    override?: boolean;\n}\n\n/**\n * Internal call signature used by `EnvapterBase`. The `path` and `processEnv`\n * fields are managed by envapt and never user-supplied.\n * @internal\n */\nexport interface LoadDotenvInput extends EnvFileOptions {\n    path: string | string[];\n    processEnv: Record<string, string>;\n    // Injected so the loader stays free of `node:fs`. Returns `undefined` when the file is absent.\n    readFile(path: string, encoding: string): string | undefined;\n}\n\n// Matches: optional `export`, KEY name, optional whitespace, `=`, optional whitespace, value tail.\n// Multi-line quoted values are handled by re-buffering subsequent lines below.\n// Bounded by anchors with linear-time quantifiers; no catastrophic backtracking risk -- justified\n// eslint-disable-next-line security/detect-unsafe-regex\nconst KEY_LINE_RE = /^\\s*(?:export\\s+)?([A-Za-z_][A-Za-z0-9_]*)\\s*=(.*)$/u;\n\n/**\n * Parse a `.env` text blob into a `Map<string, string>`.\n *\n * Supported syntax:\n * - `KEY=value` and `export KEY=value`\n * - blank lines and full-line `# comments`\n * - single-quoted `'literal'` values (no escape interpretation)\n * - double-quoted `\"value\"` values (interprets `\\n`, `\\r`, `\\t`, `\\\\`, `\\\"`)\n * - backtick-quoted values (literal, like single quotes)\n * - quoted values may span multiple lines\n * - inline `# comment` after an unquoted value (requires whitespace before `#`)\n * - empty values resolve to `\"\"`\n *\n * Mirrors dotenv's quirk where unescaped inner quotes inside a quoted value\n * are tolerated by greedy-matching to the rightmost matching quote on the\n * (possibly multi-line) value buffer. This is what lets a value like\n * `JSON=\"{\"name\":\"x\"}\"` round-trip without escaping.\n *\n * Does NOT perform `${VAR}` expansion — envapt's `Parser` handles that downstream.\n * @internal\n */\nexport function parseDotenv(src: string): Map<string, string> {\n    const out = new Map<string, string>();\n    const lines = src.split(/\\r?\\n/u);\n\n    for (let i = 0; i < lines.length; i++) {\n        const consumed = parseEntry(lines, i);\n        i = consumed.endLine;\n        if (consumed.entry) out.set(consumed.entry.key, consumed.entry.value);\n    }\n\n    return out;\n}\n\ninterface ParsedEntry {\n    key: string;\n    value: string;\n}\n\nfunction parseEntry(lines: string[], start: number): { entry: ParsedEntry | undefined; endLine: number } {\n    /* v8 ignore next -- @preserve caller bounds-checks start so this never falls back */\n    const line = lines[start] ?? '';\n    const trimmedLine = line.trim();\n    if (trimmedLine === '' || trimmedLine.startsWith('#')) return { entry: undefined, endLine: start };\n\n    const match = line.match(KEY_LINE_RE);\n    if (!match) return { entry: undefined, endLine: start };\n\n    const key = match[1] as string;\n    // Drop only leading whitespace before the value; trailing whitespace and inline comments\n    // are dealt with below depending on whether the value is quoted.\n    /* v8 ignore next -- @preserve regex group 2 always matches via `(.*)`, fallback is defensive */\n    const rest = (match[2] ?? '').replace(/^\\s+/u, '');\n    const firstChar = rest[0];\n\n    if (firstChar === '\"' || firstChar === \"'\" || firstChar === '`') {\n        const consumed = consumeQuotedValue(rest, lines, start, firstChar);\n        return { entry: { key, value: consumed.value }, endLine: consumed.endLine };\n    }\n\n    return { entry: { key, value: stripInlineComment(rest) }, endLine: start };\n}\n\nfunction consumeQuotedValue(\n    firstLineRest: string,\n    lines: string[],\n    startLine: number,\n    quote: string\n): { value: string; endLine: number } {\n    let buffer = firstLineRest;\n    let cursor = startLine;\n    let closeIdx = findLastUnescapedQuote(buffer, quote);\n\n    while (closeIdx < 0 && cursor < lines.length - 1) {\n        cursor++;\n        /* v8 ignore next -- @preserve cursor is bounded by the while condition above */\n        buffer += `\\n${lines[cursor] ?? ''}`;\n        closeIdx = findLastUnescapedQuote(buffer, quote);\n    }\n\n    const inner = closeIdx > 0 ? buffer.slice(1, closeIdx) : buffer.slice(1);\n    return { value: quote === '\"' ? unescapeDouble(inner) : inner, endLine: cursor };\n}\n\nfunction stripInlineComment(value: string): string {\n    const hashIdx = findInlineCommentStart(value);\n    const stripped = hashIdx === -1 ? value : value.slice(0, hashIdx);\n    return stripped.trimEnd();\n}\n\nfunction findInlineCommentStart(value: string): number {\n    for (let i = 0; i < value.length; i++) {\n        if (value[i] === '#' && (i === 0 || /\\s/u.test(value[i - 1] as string))) return i;\n    }\n    return -1;\n}\n\n/**\n * Find the rightmost matching closing quote in `buffer` (skipping index 0 which is the\n * opening quote). For `\"`, a quote preceded by an odd number of backslashes is escaped\n * and ignored. Single and backtick quotes do not unescape.\n */\nfunction findLastUnescapedQuote(buffer: string, quote: string): number {\n    for (let i = buffer.length - 1; i > 0; i--) {\n        if (buffer[i] !== quote) continue;\n        if (quote === '\"') {\n            let backslashes = 0;\n            let k = i - 1;\n            while (k >= 0 && buffer[k] === '\\\\') {\n                backslashes++;\n                k--;\n            }\n            if (backslashes % 2 === 1) continue; // escaped\n        }\n        return i;\n    }\n    return -1;\n}\n\nfunction unescapeDouble(raw: string): string {\n    let out = '';\n    for (let i = 0; i < raw.length; i++) {\n        const ch = raw[i];\n        if (ch !== '\\\\' || i === raw.length - 1) {\n            out += ch;\n            continue;\n        }\n        const next = raw[i + 1];\n        i++;\n        switch (next) {\n            case 'n':\n                out += '\\n';\n                break;\n            case 'r':\n                out += '\\r';\n                break;\n            case 't':\n                out += '\\t';\n                break;\n            case '\\\\':\n                out += '\\\\';\n                break;\n            case '\"':\n                out += '\"';\n                break;\n            default:\n                /* v8 ignore next -- @preserve `next` is always defined when this branch is reached (guarded above) */\n                out += `\\\\${next ?? ''}`;\n        }\n    }\n    return out;\n}\n\n/**\n * Load one or more `.env` files into a target `processEnv` map. Mirrors the\n * subset of dotenv's `config()` semantics that envapt depends on: first-wins\n * across multiple paths by default, optional `override: true`, optional\n * non-UTF8 encoding, missing files are skipped silently.\n *\n * Returns the set of keys actually written into `input.processEnv`. Skipped\n * collisions (under default `override: false`) are NOT included.\n * @internal\n */\nexport function loadDotenv(input: LoadDotenvInput): Set<string> {\n    const paths = Array.isArray(input.path) ? input.path : [input.path];\n    const encoding = input.encoding ?? 'utf8';\n    const override = input.override ?? false;\n    const written = new Set<string>();\n\n    for (const filePath of paths) {\n        const src = input.readFile(filePath, encoding);\n        if (src === undefined) {\n            debugWarn(`could not read ${filePath}`);\n            continue;\n        }\n\n        const parsed = parseDotenv(src);\n        debugVerbose(`loaded ${filePath}: ${parsed.size} ${parsed.size === 1 ? 'key' : 'keys'}`);\n        for (const [key, value] of parsed) {\n            const exists = Object.prototype.hasOwnProperty.call(input.processEnv, key);\n            if (!exists || override) {\n                input.processEnv[key] = value;\n                written.add(key);\n                debugVerbose(`${filePath} -> ${key}`);\n            }\n        }\n    }\n\n    return written;\n}\n"],"mappings":"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"}

package/dist/portable/infra/Error.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"Error.mjs","names":[],"sources":["../../../src/infra/Error.ts"],"sourcesContent":["/* eslint-disable no-magic-numbers */\nimport type { StandardSchemaV1 } from './StandardSchema';\n\n/**\n * Numeric codes carried by {@link EnvaptError.code}, grouped by fallback (1xx), converter (2xx),\n * and configuration (3xx) failures.\n */\nexport enum EnvaptErrorCodes {\n    // Fallback related errors\n    /** Thrown when an invalid fallback value is provided */\n    InvalidFallback = 101,\n    /** Thrown when fallback value type doesn't match expected converter type */\n    InvalidFallbackType = 102,\n    /** Thrown when array fallback contains elements of wrong type */\n    ArrayFallbackElementTypeMismatch = 103,\n    /** Thrown when fallback type doesn't match the specified converter */\n    FallbackConverterTypeMismatch = 104,\n    /** Thrown when a time-string fallback is malformed (does not match the required `<number><unit>` format) */\n    MalformedTimeFallback = 105,\n\n    // Converter related errors\n    /** Thrown when invalid array converter configuration is provided */\n    InvalidArrayConverterType = 201,\n    /** Thrown when an invalid built-in converter is specified */\n    InvalidBuiltInConverter = 202,\n    /** Thrown when a custom converter is not a function */\n    InvalidCustomConverter = 203,\n    /** Thrown when converter type is not recognized */\n    InvalidConverterType = 204,\n    /** Thrown when primitive type coercion on fallback value fails */\n    PrimitiveCoercionFailed = 205,\n    /** Thrown when an array element fails to convert to the configured element type */\n    ArrayElementConversionFailed = 206,\n    /** Thrown under strict mode when an array element is empty or whitespace only */\n    EmptyArrayElement = 207,\n    /** Thrown when a Standard Schema returns issues for a non-empty env value */\n    SchemaValidationFailed = 208,\n    /** Thrown when a Standard Schema's `validate` itself throws (e.g. a refinement that crashes) */\n    SchemaThrew = 209,\n\n    // Other errors\n    /** Thrown when delimiter is missing in array converter configuration */\n    // This doesn't happen because 203 is thrown when object without delimiter is passed\n    MissingDelimiter = 301,\n    /** Thrown when invalid user-defined configuration is provided */\n    InvalidUserDefinedConfig = 302,\n    /** Thrown when specified environment files don't exist */\n    EnvFilesNotFound = 303,\n    /** Thrown when no valid environment key is provided */\n    InvalidKeyInput = 304,\n    /** Thrown when a required environment value is missing or empty (post-trim) */\n    MissingEnvValue = 305,\n    /** Thrown when a file-based API (envPaths, baseDir, configureProfiles) is used on a source without filesystem support */\n    FileApiUnsupported = 306,\n    /** Thrown when an environment value is read before a source is bound via Envapter.useSource */\n    NoSourceBound = 307,\n    /** Thrown when `merge` is called with no members, or with more than one filesystem-backed source */\n    InvalidMergedSource = 308\n}\n\ninterface EnvaptErrorOptions {\n    issues?: readonly StandardSchemaV1.Issue[];\n    cause?: unknown;\n}\n\n/**\n * Custom error for better DX and debugging when using Envapt.\n *\n * @example\n * ```ts\n * throw new EnvaptError(EnvaptErrorCodes.InvalidFallback, \"Invalid fallback value provided for environment variable.\");\n * ```\n */\nexport class EnvaptError extends Error {\n    /** The {@link EnvaptErrorCodes} value identifying what failed. */\n    public readonly code: EnvaptErrorCodes;\n    /**\n     * Populated only for {@link EnvaptErrorCodes.SchemaValidationFailed} (208). For every other\n     * code this is `undefined`. Lets callers do `if (err.code === 208) err.issues?.forEach(...)`\n     * without a type cast.\n     */\n    public readonly issues: readonly StandardSchemaV1.Issue[] | undefined;\n\n    /** Create an error carrying an {@link EnvaptErrorCodes} code, a message, and optional `cause` / `issues`. */\n    constructor(code: EnvaptErrorCodes, message: string, options?: EnvaptErrorOptions) {\n        super(message, options?.cause !== undefined ? { cause: options.cause } : undefined);\n        this.name = `EnvaptError [${code}]`;\n        this.code = code;\n        this.issues = options?.issues;\n    }\n}\n"],"mappings":"AAOA,IAAY,EAAL,SAAA,EAAA,OAGH,GAAA,EAAA,gBAAA,KAAA,kBAEA,EAAA,EAAA,oBAAA,KAAA,sBAEA,EAAA,EAAA,iCAAA,KAAA,mCAEA,EAAA,EAAA,8BAAA,KAAA,gCAEA,EAAA,EAAA,sBAAA,KAAA,wBAIA,EAAA,EAAA,0BAAA,KAAA,4BAEA,EAAA,EAAA,wBAAA,KAAA,0BAEA,EAAA,EAAA,uBAAA,KAAA,yBAEA,EAAA,EAAA,qBAAA,KAAA,uBAEA,EAAA,EAAA,wBAAA,KAAA,0BAEA,EAAA,EAAA,6BAAA,KAAA,+BAEA,EAAA,EAAA,kBAAA,KAAA,oBAEA,EAAA,EAAA,uBAAA,KAAA,yBAEA,EAAA,EAAA,YAAA,KAAA,cAKA,EAAA,EAAA,iBAAA,KAAA,mBAEA,EAAA,EAAA,yBAAA,KAAA,2BAEA,EAAA,EAAA,iBAAA,KAAA,mBAEA,EAAA,EAAA,gBAAA,KAAA,kBAEA,EAAA,EAAA,gBAAA,KAAA,kBAEA,EAAA,EAAA,mBAAA,KAAA,qBAEA,EAAA,EAAA,cAAA,KAAA,gBAEA,EAAA,EAAA,oBAAA,KAAA,uBACJ,EAAA,CAAA,CAAA,EAeA,IAAa,EAAb,cAAiC,KAAM,CAEnC,KAMA,OAGA,YAAY,EAAwB,EAAiB,EAA8B,CAC/E,MAAM,EAAS,GAAS,QAAU,IAAA,GAAuC,IAAA,GAA3B,CAAE,MAAO,EAAQ,KAAM,CAAa,EAClF,KAAK,KAAO,gBAAgB,EAAK,GACjC,KAAK,KAAO,EACZ,KAAK,OAAS,GAAS,MAC3B,CACJ"}
+{"version":3,"file":"Error.mjs","names":[],"sources":["../../../src/infra/Error.ts"],"sourcesContent":["/* eslint-disable no-magic-numbers */\nimport type { StandardSchemaV1 } from './StandardSchema';\n\n/**\n * Numeric codes carried by {@link EnvaptError.code}, grouped by fallback (1xx), converter (2xx),\n * and configuration (3xx) failures.\n * @see {@link https://envapt.materwelon.dev/docs/errors#codes}\n */\nexport enum EnvaptErrorCodes {\n    // Fallback related errors\n    /** Thrown when an invalid fallback value is provided */\n    InvalidFallback = 101,\n    /** Thrown when fallback value type doesn't match expected converter type */\n    InvalidFallbackType = 102,\n    /** Thrown when array fallback contains elements of wrong type */\n    ArrayFallbackElementTypeMismatch = 103,\n    /** Thrown when fallback type doesn't match the specified converter */\n    FallbackConverterTypeMismatch = 104,\n    /** Thrown when a time-string fallback is malformed (does not match the required `<number><unit>` format) */\n    MalformedTimeFallback = 105,\n\n    // Converter related errors\n    /** Thrown when invalid array converter configuration is provided */\n    InvalidArrayConverterType = 201,\n    /** Thrown when an invalid built-in converter is specified */\n    InvalidBuiltInConverter = 202,\n    /** Thrown when a custom converter is not a function */\n    InvalidCustomConverter = 203,\n    /** Thrown when converter type is not recognized */\n    InvalidConverterType = 204,\n    /** Thrown when primitive type coercion on fallback value fails */\n    PrimitiveCoercionFailed = 205,\n    /** Thrown when an array element fails to convert to the configured element type */\n    ArrayElementConversionFailed = 206,\n    /** Thrown under strict mode when an array element is empty or whitespace only */\n    EmptyArrayElement = 207,\n    /** Thrown when a Standard Schema returns issues for a non-empty env value */\n    SchemaValidationFailed = 208,\n    /** Thrown when a Standard Schema's `validate` itself throws (e.g. a refinement that crashes) */\n    SchemaThrew = 209,\n\n    // Other errors\n    /** Thrown when delimiter is missing in array converter configuration */\n    // This doesn't happen because 203 is thrown when object without delimiter is passed\n    MissingDelimiter = 301,\n    /** Thrown when invalid user-defined configuration is provided */\n    InvalidUserDefinedConfig = 302,\n    /** Thrown when specified environment files don't exist */\n    EnvFilesNotFound = 303,\n    /** Thrown when no valid environment key is provided */\n    InvalidKeyInput = 304,\n    /** Thrown when a required environment value is missing or empty (post-trim) */\n    MissingEnvValue = 305,\n    /** Thrown when a file-based API (envPaths, baseDir, configureProfiles) is used on a source without filesystem support */\n    FileApiUnsupported = 306,\n    /** Thrown when an environment value is read before a source is bound via Envapter.useSource */\n    NoSourceBound = 307,\n    /** Thrown when `merge` is called with no members, or with more than one filesystem-backed source */\n    InvalidMergedSource = 308\n}\n\ninterface EnvaptErrorOptions {\n    issues?: readonly StandardSchemaV1.Issue[];\n    cause?: unknown;\n}\n\n/**\n * Custom error for better DX and debugging when using Envapt.\n *\n * @example\n * ```ts\n * throw new EnvaptError(EnvaptErrorCodes.InvalidFallback, \"Invalid fallback value provided for environment variable.\");\n * ```\n * @see {@link https://envapt.materwelon.dev/docs/errors#the-error-shape}\n */\nexport class EnvaptError extends Error {\n    /** The {@link EnvaptErrorCodes} value identifying what failed. */\n    public readonly code: EnvaptErrorCodes;\n    /**\n     * Populated only for {@link EnvaptErrorCodes.SchemaValidationFailed} (208). For every other\n     * code this is `undefined`. Lets callers do `if (err.code === 208) err.issues?.forEach(...)`\n     * without a type cast.\n     */\n    public readonly issues: readonly StandardSchemaV1.Issue[] | undefined;\n\n    /** Create an error carrying an {@link EnvaptErrorCodes} code, a message, and optional `cause` / `issues`. */\n    constructor(code: EnvaptErrorCodes, message: string, options?: EnvaptErrorOptions) {\n        super(message, options?.cause !== undefined ? { cause: options.cause } : undefined);\n        this.name = `EnvaptError [${code}]`;\n        this.code = code;\n        this.issues = options?.issues;\n    }\n}\n"],"mappings":"AAQA,IAAY,EAAL,SAAA,EAAA,OAGH,GAAA,EAAA,gBAAA,KAAA,kBAEA,EAAA,EAAA,oBAAA,KAAA,sBAEA,EAAA,EAAA,iCAAA,KAAA,mCAEA,EAAA,EAAA,8BAAA,KAAA,gCAEA,EAAA,EAAA,sBAAA,KAAA,wBAIA,EAAA,EAAA,0BAAA,KAAA,4BAEA,EAAA,EAAA,wBAAA,KAAA,0BAEA,EAAA,EAAA,uBAAA,KAAA,yBAEA,EAAA,EAAA,qBAAA,KAAA,uBAEA,EAAA,EAAA,wBAAA,KAAA,0BAEA,EAAA,EAAA,6BAAA,KAAA,+BAEA,EAAA,EAAA,kBAAA,KAAA,oBAEA,EAAA,EAAA,uBAAA,KAAA,yBAEA,EAAA,EAAA,YAAA,KAAA,cAKA,EAAA,EAAA,iBAAA,KAAA,mBAEA,EAAA,EAAA,yBAAA,KAAA,2BAEA,EAAA,EAAA,iBAAA,KAAA,mBAEA,EAAA,EAAA,gBAAA,KAAA,kBAEA,EAAA,EAAA,gBAAA,KAAA,kBAEA,EAAA,EAAA,mBAAA,KAAA,qBAEA,EAAA,EAAA,cAAA,KAAA,gBAEA,EAAA,EAAA,oBAAA,KAAA,uBACJ,EAAA,CAAA,CAAA,EAgBA,IAAa,EAAb,cAAiC,KAAM,CAEnC,KAMA,OAGA,YAAY,EAAwB,EAAiB,EAA8B,CAC/E,MAAM,EAAS,GAAS,QAAU,IAAA,GAAuC,IAAA,GAA3B,CAAE,MAAO,EAAQ,KAAM,CAAa,EAClF,KAAK,KAAO,gBAAgB,EAAK,GACjC,KAAK,KAAO,EACZ,KAAK,OAAS,GAAS,MAC3B,CACJ"}

package/dist/portable/infra/runtime.mjs

@@ -1,2 +1,2 @@
-let e=e=>{console.error(e)},t=()=>({});function n(t){e(t)}function r(){return t()}function i(e){t=()=>e.readVars()}export{i as bindRuntimeFromSource,r as readRuntimeEnv,n as writeRuntimeLine};
+let e=e=>{console.error(e)},t=()=>({}),n;function r(t){e(t)}function i(e){let r=t()[e];if(r!==void 0)return r;try{return n?.(e)}catch{return}}function a(e){t=()=>e.readVars();let r=e.readVar;n=typeof r==`function`?r.bind(e):void 0}export{a as bindRuntimeFromSource,i as readRuntimeVar,r as writeRuntimeLine};
 //# sourceMappingURL=runtime.mjs.map

package/dist/portable/infra/runtime.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.mjs","names":[],"sources":["../../../src/infra/runtime.ts"],"sourcesContent":["import type { Source } from '../types';\n\n// importing Debug back into EnvapterBase would cycle, so the source and sink are injected via the setters below.\n/* v8 ignore start -- @preserve replaced at load on Node, so the Node suite never runs these defaults */\nlet sink: (line: string) => void = (line) => {\n    // eslint-disable-next-line no-console -- the off-Node fallback log sink\n    console.error(line);\n};\nlet envReader: () => Record<string, string> = () => ({});\n/* v8 ignore stop */\n\nexport function setRuntimeSink(fn: (line: string) => void): void {\n    sink = fn;\n}\n\nexport function writeRuntimeLine(line: string): void {\n    sink(line);\n}\n\nexport function readRuntimeEnv(): Record<string, string> {\n    return envReader();\n}\n\nexport function bindRuntimeFromSource(source: Source): void {\n    envReader = (): Record<string, string> => source.readVars();\n}\n"],"mappings":"AAIA,IAAI,EAAgC,GAAS,CAEzC,QAAQ,MAAM,CAAI,CACtB,EACI,OAAiD,CAAC,GAOtD,SAAgB,EAAiB,EAAoB,CACjD,EAAK,CAAI,CACb,CAEA,SAAgB,GAAyC,CACrD,OAAO,EAAU,CACrB,CAEA,SAAgB,EAAsB,EAAsB,CACxD,MAA0C,EAAO,SAAS,CAC9D"}
+{"version":3,"file":"runtime.mjs","names":[],"sources":["../../../src/infra/runtime.ts"],"sourcesContent":["import type { Source } from '../types';\n\n// importing Debug back into EnvapterBase would cycle, so the source and sink are injected via the setters below.\n/* v8 ignore start -- @preserve replaced at load on Node so the Node suite never runs these defaults */\nlet sink: (line: string) => void = (line) => {\n    // eslint-disable-next-line no-console -- the off-Node fallback log sink\n    console.error(line);\n};\nlet envReader: () => Record<string, string> = () => ({});\nlet varReader: ((key: string) => string | undefined) | undefined;\n/* v8 ignore stop */\n\nexport function setRuntimeSink(fn: (line: string) => void): void {\n    sink = fn;\n}\n\nexport function writeRuntimeLine(line: string): void {\n    sink(line);\n}\n\n// check snapshot first, then the source's per-key reader, so a reader source (empty snapshot) still resolves a key\nexport function readRuntimeVar(key: string): string | undefined {\n    const fromSnapshot = envReader()[key];\n    if (fromSnapshot !== undefined) return fromSnapshot;\n    // ENVAPT_DEBUG resolves through here, so a throwing reader must not abort the config load that triggered it\n    try {\n        return varReader?.(key);\n    } catch {\n        return undefined;\n    }\n}\n\nexport function bindRuntimeFromSource(source: Source): void {\n    envReader = (): Record<string, string> => source.readVars();\n    const readVar = source.readVar;\n    varReader = typeof readVar === 'function' ? readVar.bind(source) : undefined;\n}\n"],"mappings":"AAIA,IAAI,EAAgC,GAAS,CAEzC,QAAQ,MAAM,CAAI,CACtB,EACI,OAAiD,CAAC,GAClD,EAOJ,SAAgB,EAAiB,EAAoB,CACjD,EAAK,CAAI,CACb,CAGA,SAAgB,EAAe,EAAiC,CAC5D,IAAM,EAAe,EAAU,CAAC,CAAC,GACjC,GAAI,IAAiB,IAAA,GAAW,OAAO,EAEvC,GAAI,CACA,OAAO,IAAY,CAAG,CAC1B,MAAQ,CACJ,MACJ,CACJ,CAEA,SAAgB,EAAsB,EAAsB,CACxD,MAA0C,EAAO,SAAS,EAC1D,IAAM,EAAU,EAAO,QACvB,EAAY,OAAO,GAAY,WAAa,EAAQ,KAAK,CAAM,EAAI,IAAA,EACvE"}

package/dist/portable/sources/PortableSource.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"PortableSource.mjs","names":[],"sources":["../../../src/sources/PortableSource.ts"],"sourcesContent":["import { coerceToStringRecord } from './coerce';\n\nimport type { BareSource } from '../types';\n\n/**\n * Environment source seeded from an object you provide, for every runtime without a filesystem. The\n * config your bundler injects into a browser build (Vite's `import.meta.env`, a webpack `DefinePlugin`\n * global), the Cloudflare `env` binding, a Vercel Edge or Fastly config object, a test fixture, or any\n * plain object. Pass it straight through. Non-string values are JSON-stringified so the converters\n * still apply, which means they must be JSON-serializable. Without a filesystem the `.env` cascade and\n * file APIs do not apply.\n * @public\n */\nexport class PortableSource implements BareSource {\n    /** Always `false`. With no filesystem, the `.env` cascade and file APIs do not apply. */\n    readonly supportsFiles = false;\n    private readonly vars: Record<string, string>;\n\n    /** Seed the source from `vars`. Non-string values are JSON-stringified so the converters still apply. */\n    constructor(vars: object) {\n        this.vars = coerceToStringRecord(vars);\n    }\n\n    /** Returns a snapshot clone of the provided object as plain strings. */\n    readVars(): Record<string, string> {\n        return { ...this.vars };\n    }\n}\n"],"mappings":"oDAaA,IAAa,EAAb,KAAkD,CAE9C,cAAyB,GACzB,KAGA,YAAY,EAAc,CACtB,KAAK,KAAO,EAAqB,CAAI,CACzC,CAGA,UAAmC,CAC/B,MAAO,CAAE,GAAG,KAAK,IAAK,CAC1B,CACJ"}
+{"version":3,"file":"PortableSource.mjs","names":[],"sources":["../../../src/sources/PortableSource.ts"],"sourcesContent":["import { coerceToStringRecord } from './coerce';\n\nimport type { BareSource } from '../types';\n\n/**\n * Environment source seeded from an object you provide, for every runtime without a filesystem. The\n * config your bundler injects into a browser build (Vite's `import.meta.env`, a webpack `DefinePlugin`\n * global), the Cloudflare `env` binding, a Vercel Edge or Fastly config object, a test fixture, or any\n * plain object. Pass it straight through. Non-string values are JSON-stringified so the converters\n * still apply, which means they must be JSON-serializable. Without a filesystem the `.env` cascade and\n * file APIs do not apply.\n * @public\n * @see {@link https://envapt.materwelon.dev/docs/sources#the-providers}\n */\nexport class PortableSource implements BareSource {\n    /** Always `false`. With no filesystem, the `.env` cascade and file APIs do not apply. */\n    readonly supportsFiles = false;\n    private readonly vars: Record<string, string>;\n\n    /** Seed the source from `vars`. Non-string values are JSON-stringified so the converters still apply. */\n    constructor(vars: object) {\n        this.vars = coerceToStringRecord(vars);\n    }\n\n    /** Returns a snapshot clone of the provided object as plain strings. */\n    readVars(): Record<string, string> {\n        return { ...this.vars };\n    }\n}\n"],"mappings":"oDAcA,IAAa,EAAb,KAAkD,CAE9C,cAAyB,GACzB,KAGA,YAAY,EAAc,CACtB,KAAK,KAAO,EAAqB,CAAI,CACzC,CAGA,UAAmC,CAC/B,MAAO,CAAE,GAAG,KAAK,IAAK,CAC1B,CACJ"}

package/dist/portable/sources/merge.mjs

@@ -1,2 +1,2 @@
-import{EnvaptError as e}from"../infra/Error.mjs";function t(...t){if(t.length===0)throw new e(308,`merge requires at least one source.`);let n=t.filter(e=>e.supportsFiles===!0);if(n.length>1)throw new e(308,`merge accepts at most one filesystem-backed source, so the .env cascade and file APIs route to a single member.`);let r=()=>{let e={};for(let n of t)Object.assign(e,n.readVars());return e},i=n[0];return i?{readVars:r,supportsFiles:!0,readFile:(e,t)=>i.readFile(e,t),resolvePath:(e,t)=>i.resolvePath(e,t),normalizeBaseDir:e=>i.normalizeBaseDir(e),writeVars:e=>i.writeVars(e)}:{readVars:r}}export{t as merge};
+import{EnvaptError as e}from"../infra/Error.mjs";import{normalizeSource as t}from"./normalizeSource.mjs";function n(...n){if(n.length===0)throw new e(308,`merge requires at least one source.`);let r=n.map(t),i=r.filter(e=>e.supportsFiles===!0);if(i.length>1)throw new e(308,`merge accepts at most one filesystem-backed source, so the .env cascade and file APIs route to a single member.`);let a=()=>{let e={};for(let t of r)Object.assign(e,t.readVars());return e},o=r.filter(e=>typeof e.readVar==`function`),s=o.length===0?void 0:e=>{for(let t=o.length-1;t>=0;t--){let n=o[t]?.readVar(e);if(n!==void 0)return n}},c=i[0];if(!c){let e={readVars:a};return s&&(e.readVar=s),e}let l={readVars:a,supportsFiles:!0,readFile:(e,t)=>c.readFile(e,t),resolvePath:(e,t)=>c.resolvePath(e,t),normalizeBaseDir:e=>c.normalizeBaseDir(e),writeVars:e=>c.writeVars(e)};return s&&(l.readVar=s),l}export{n as merge};
 //# sourceMappingURL=merge.mjs.map

package/dist/portable/sources/merge.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"merge.mjs","names":[],"sources":["../../../src/sources/merge.ts"],"sourcesContent":["import { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { FileCapableSource, Source } from '../types';\n\n/**\n * Compose several sources into one, read last-wins. A later member's value overrides an earlier\n * member's value for the same key. Bind the result with `Envapter.useSource`. Throws\n * {@link EnvaptErrorCodes.InvalidMergedSource} with no members or with more than one file-backed member.\n * @public\n */\nexport function merge(...members: Source[]): Source {\n    if (members.length === 0) {\n        throw new EnvaptError(EnvaptErrorCodes.InvalidMergedSource, 'merge requires at least one source.');\n    }\n\n    const fileMembers = members.filter((m): m is FileCapableSource => m.supportsFiles === true);\n    if (fileMembers.length > 1) {\n        throw new EnvaptError(\n            EnvaptErrorCodes.InvalidMergedSource,\n            'merge accepts at most one filesystem-backed source, so the .env cascade and file APIs route to a single member.'\n        );\n    }\n\n    const readVars = (): Record<string, string> => {\n        const merged: Record<string, string> = {};\n        for (const m of members) Object.assign(merged, m.readVars());\n        return merged;\n    };\n\n    const fileMember = fileMembers[0];\n    if (!fileMember) return { readVars };\n\n    const fileCapable: FileCapableSource = {\n        readVars,\n        supportsFiles: true,\n        readFile: (path, encoding) => fileMember.readFile(path, encoding),\n        resolvePath: (baseDir, candidate) => fileMember.resolvePath(baseDir, candidate),\n        normalizeBaseDir: (value) => fileMember.normalizeBaseDir(value),\n        writeVars: (vars) => fileMember.writeVars(vars)\n    };\n    return fileCapable;\n}\n"],"mappings":"iDAUA,SAAgB,EAAM,GAAG,EAA2B,CAChD,GAAI,EAAQ,SAAW,EACnB,MAAM,IAAI,EAAA,IAAkD,qCAAqC,EAGrG,IAAM,EAAc,EAAQ,OAAQ,GAA8B,EAAE,gBAAkB,EAAI,EAC1F,GAAI,EAAY,OAAS,EACrB,MAAM,IAAI,EAAA,IAEN,iHACJ,EAGJ,IAAM,MAAyC,CAC3C,IAAM,EAAiC,CAAC,EACxC,IAAK,IAAM,KAAK,EAAS,OAAO,OAAO,EAAQ,EAAE,SAAS,CAAC,EAC3D,OAAO,CACX,EAEM,EAAa,EAAY,GAW/B,OAVK,EAUE,CAPH,WACA,cAAe,GACf,UAAW,EAAM,IAAa,EAAW,SAAS,EAAM,CAAQ,EAChE,aAAc,EAAS,IAAc,EAAW,YAAY,EAAS,CAAS,EAC9E,iBAAmB,GAAU,EAAW,iBAAiB,CAAK,EAC9D,UAAY,GAAS,EAAW,UAAU,CAAI,CAEjC,EAVO,CAAE,UAAS,CAWvC"}
+{"version":3,"file":"merge.mjs","names":[],"sources":["../../../src/sources/merge.ts"],"sourcesContent":["import { normalizeSource } from './normalizeSource';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { BareSource, FileCapableSource, Source } from '../types';\n\n/**\n * Compose several sources into one, read last-wins. A later member's `readVars()` value overrides an\n * earlier member's for the same key. A member may be a `(key) => string | undefined` reader for a\n * source that reads one key at a time, and it fills a key missing from every snapshot. Bind the result\n * with `Envapter.useSource`. Throws {@link EnvaptErrorCodes.InvalidMergedSource} with no members or with\n * more than one file-backed member.\n * @public\n * @see {@link https://envapt.materwelon.dev/docs/sources#combining-sources}\n */\nexport function merge(...members: (Source | ((key: string) => string | undefined))[]): Source {\n    if (members.length === 0) {\n        throw new EnvaptError(EnvaptErrorCodes.InvalidMergedSource, 'merge requires at least one source.');\n    }\n\n    const sources = members.map(normalizeSource);\n\n    const fileMembers = sources.filter((m): m is FileCapableSource => m.supportsFiles === true);\n    if (fileMembers.length > 1) {\n        throw new EnvaptError(\n            EnvaptErrorCodes.InvalidMergedSource,\n            'merge accepts at most one filesystem-backed source, so the .env cascade and file APIs route to a single member.'\n        );\n    }\n\n    const readVars = (): Record<string, string> => {\n        const merged: Record<string, string> = {};\n        for (const m of sources) Object.assign(merged, m.readVars());\n        return merged;\n    };\n\n    const readers = sources.filter(\n        (m): m is Source & { readVar: (key: string) => string | undefined } => typeof m.readVar === 'function'\n    );\n    const readVar =\n        readers.length === 0\n            ? undefined\n            : (key: string): string | undefined => {\n                  // last reader that answers wins, so scan from the end and return the first defined value\n                  for (let i = readers.length - 1; i >= 0; i--) {\n                      const found = readers[i]?.readVar(key);\n                      if (found !== undefined) return found;\n                  }\n                  return undefined;\n              };\n\n    const fileMember = fileMembers[0];\n    if (!fileMember) {\n        const bare: BareSource = { readVars };\n        if (readVar) bare.readVar = readVar;\n        return bare;\n    }\n\n    const fileCapable: FileCapableSource = {\n        readVars,\n        supportsFiles: true,\n        readFile: (path, encoding) => fileMember.readFile(path, encoding),\n        resolvePath: (baseDir, candidate) => fileMember.resolvePath(baseDir, candidate),\n        normalizeBaseDir: (value) => fileMember.normalizeBaseDir(value),\n        writeVars: (vars) => fileMember.writeVars(vars)\n    };\n    if (readVar) fileCapable.readVar = readVar;\n    return fileCapable;\n}\n"],"mappings":"yGAcA,SAAgB,EAAM,GAAG,EAAqE,CAC1F,GAAI,EAAQ,SAAW,EACnB,MAAM,IAAI,EAAA,IAAkD,qCAAqC,EAGrG,IAAM,EAAU,EAAQ,IAAI,CAAe,EAErC,EAAc,EAAQ,OAAQ,GAA8B,EAAE,gBAAkB,EAAI,EAC1F,GAAI,EAAY,OAAS,EACrB,MAAM,IAAI,EAAA,IAEN,iHACJ,EAGJ,IAAM,MAAyC,CAC3C,IAAM,EAAiC,CAAC,EACxC,IAAK,IAAM,KAAK,EAAS,OAAO,OAAO,EAAQ,EAAE,SAAS,CAAC,EAC3D,OAAO,CACX,EAEM,EAAU,EAAQ,OACnB,GAAsE,OAAO,EAAE,SAAY,UAChG,EACM,EACF,EAAQ,SAAW,EACb,IAAA,GACC,GAAoC,CAEjC,IAAK,IAAI,EAAI,EAAQ,OAAS,EAAG,GAAK,EAAG,IAAK,CAC1C,IAAM,EAAQ,EAAQ,EAAE,EAAE,QAAQ,CAAG,EACrC,GAAI,IAAU,IAAA,GAAW,OAAO,CACpC,CAEJ,EAEJ,EAAa,EAAY,GAC/B,GAAI,CAAC,EAAY,CACb,IAAM,EAAmB,CAAE,UAAS,EAEpC,OADI,IAAS,EAAK,QAAU,GACrB,CACX,CAEA,IAAM,EAAiC,CACnC,WACA,cAAe,GACf,UAAW,EAAM,IAAa,EAAW,SAAS,EAAM,CAAQ,EAChE,aAAc,EAAS,IAAc,EAAW,YAAY,EAAS,CAAS,EAC9E,iBAAmB,GAAU,EAAW,iBAAiB,CAAK,EAC9D,UAAY,GAAS,EAAW,UAAU,CAAI,CAClD,EAEA,OADI,IAAS,EAAY,QAAU,GAC5B,CACX"}

package/dist/portable/sources/normalizeSource.mjs

@@ -0,0 +1,2 @@
+function e(e){return typeof e==`function`?{supportsFiles:!1,readVars:()=>({}),readVar:e}:e}export{e as normalizeSource};
+//# sourceMappingURL=normalizeSource.mjs.map

package/dist/portable/sources/normalizeSource.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeSource.mjs","names":[],"sources":["../../../src/sources/normalizeSource.ts"],"sourcesContent":["import type { Source } from '../types';\n\nexport function normalizeSource(source: Source | ((key: string) => string | undefined)): Source {\n    return typeof source === 'function' ? { supportsFiles: false, readVars: () => ({}), readVar: source } : source;\n}\n"],"mappings":"AAEA,SAAgB,EAAgB,EAAgE,CAC5F,OAAO,OAAO,GAAW,WAAa,CAAE,cAAe,GAAO,cAAiB,CAAC,GAAI,QAAS,CAAO,EAAI,CAC5G"}

package/dist/types/converters/Converters.d.mts

@@ -13,15 +13,12 @@ declare const SCALAR: {
   readonly Date: "date";
   readonly Time: "time";
 };
-/**
- * String tokens for every built-in scalar converter.
- * @public
- */
 type ConverterToken = (typeof SCALAR)[keyof typeof SCALAR];
 /**
  * Custom element converter for use inside {@link Converters.array}. Receives the trimmed,
  * non-empty raw string for one array slot and returns the parsed value.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/converters#custom-converters}
  */
 type CustomElementConverter<TReturn = unknown> = (raw: string) => TReturn;
 type ArrayElement = Exclude<ConverterToken, 'json' | 'regexp'> | CustomElementConverter;
@@ -30,11 +27,6 @@ interface ArrayOf<TElement extends ArrayElement = ArrayElement> {
   readonly of: TElement;
   readonly delimiter: string;
 }
-/**
- * Runtime type guard for tokens produced by {@link Converters.array}.
- * @internal
- */
-declare function isArrayOf(value: unknown): value is ArrayOf;
 type ArrayScalarElement = Exclude<ConverterToken, 'json' | 'regexp'>;
 declare function buildArrayConverter<TReturn>(opts: {
   of: CustomElementConverter<TReturn>;
@@ -61,6 +53,7 @@ declare function buildArrayConverter(opts?: {
  * ```
  *
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/converters#built-in-tokens}
  */
 declare const Converters: {
   readonly array: typeof buildArrayConverter;
@@ -78,5 +71,5 @@ declare const Converters: {
   readonly Time: "time";
 };
 //#endregion
-export { ArrayOf, ConverterToken, Converters, CustomElementConverter, isArrayOf };
+export { ArrayOf, ConverterToken, Converters, CustomElementConverter };
 //# sourceMappingURL=Converters.d.mts.map

package/dist/types/core/AdvancedMethods.d.mts

@@ -18,6 +18,8 @@ declare class AdvancedMethods extends PrimitiveMethods {
    * Supports both scalar tokens (e.g. `Converters.Number`) and `ArrayOf<...>` tokens
    * produced by `Converters.array(...)`. The key can be a single name or an ordered list.
    * The first defined value wins.
+   * @see {@link https://envapt.materwelon.dev/docs/envapter#converters}
+   * @see {@link https://envapt.materwelon.dev/docs/converters#custom-converters}
    */
   static getUsing<TFallback extends TimeFallback | undefined = undefined>(key: EnvKeyInput, converter: 'time', fallback?: TFallback): ConditionalReturn<number, TFallback>;
   static getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(key: EnvKeyInput, converter: TConverter, fallback?: TFallback): AdvancedConverterReturn<TConverter, TFallback>;
@@ -31,6 +33,8 @@ declare class AdvancedMethods extends PrimitiveMethods {
   /**
    * Get an environment variable using a custom converter function.
    * Accepts a single key or an ordered list for automatic fallback.
+   * @see {@link https://envapt.materwelon.dev/docs/envapter#converters}
+   * @see {@link https://envapt.materwelon.dev/docs/converters#custom-converters}
    */
   static getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(key: EnvKeyInput, converter: ConverterFunction<TReturnType>, fallback?: TFallback): ConditionalReturn<TReturnType, TFallback>;
   /**
@@ -41,6 +45,8 @@ declare class AdvancedMethods extends PrimitiveMethods {
    * Read a required environment variable and convert it, throwing `MissingEnvValue` when the value
    * is missing or empty. Returns the non-undefined converter output. Accepts a built-in or `ArrayOf`
    * token, or a custom parser function. The key can be a single name or an ordered list.
+   * @see {@link https://envapt.materwelon.dev/docs/envapter#fail-fast-on-missing-values}
+   * @see {@link https://envapt.materwelon.dev/docs/converters#require-a-converted-value}
    */
   static getRequired<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, converter: TConverter): InferConverterReturnType<TConverter>;
   static getRequired<TReturnType>(key: EnvKeyInput, converter: ConverterFunction<TReturnType, string>): TReturnType;
@@ -56,6 +62,8 @@ declare class AdvancedMethods extends PrimitiveMethods {
    * `MissingEnvValue` listing them all. Pass a `casing` (`'camelCase'`, `'PascalCase'`, or
    * `'kebab-case'`) to rename the record keys, splitting on underscores, which assumes the
    * conventional SCREAMING_SNAKE env-var names. With no casing the keys stay as-is.
+   * @see {@link https://envapt.materwelon.dev/docs/envapter#fail-fast-on-missing-values}
+   * @see {@link https://envapt.materwelon.dev/docs/converters#require-a-converted-value}
    */
   static getRequiredAll<Spec extends RequiredSpec, Casing extends KeyCasing | undefined = undefined>(spec: Spec, casing?: Casing): { [K in keyof Spec as RecaseKey<K & string, Casing>]: InferSpecField<Spec[K]> };
   /**
@@ -76,6 +84,7 @@ declare class AdvancedMethods extends PrimitiveMethods {
    * import { z } from 'zod';
    * const port = Envapter.parse('PORT', z.coerce.number().min(1024).max(65535), 3000);
    * ```
+   * @see {@link https://envapt.materwelon.dev/docs/standard-schema#any-conformant-validator-or-none}
    */
   static parse<Schema extends StandardSchemaV1>(key: EnvKeyInput, schema: SchemaConstraint<Schema>, fallback?: InferSchemaOutput<Schema>): InferSchemaOutput<Schema>;
   /**

package/dist/types/core/EnvapterBase.d.mts

@@ -9,6 +9,7 @@ declare abstract class EnvapterBase {
   /**
    * Enable or disable strict mode. Default `false`. Setting refreshes the cache so
    * previously-cached converted values get re-evaluated under the new rule.
+   * @see {@link https://envapt.materwelon.dev/docs/strict-mode#what-strict-mode-changes}
    */
   static set strict(value: boolean);
   static get strict(): boolean;
@@ -16,6 +17,7 @@ declare abstract class EnvapterBase {
    * Set the debug log level. Defaults to `silent`. When unset, reads `ENVAPT_DEBUG` from the
    * bound source on first access. The setter overrides any env-var value. Output goes to stderr
    * on Node (the console elsewhere), prefixed with `[envapt]`.
+   * @see {@link https://envapt.materwelon.dev/docs/configuration#debug-logging}
    */
   static set debug(level: DebugLevel);
   static get debug(): DebugLevel;
@@ -29,6 +31,7 @@ declare abstract class EnvapterBase {
    * Flipping `false → true` mirrors the existing tracked delta immediately (no cache
    * refresh). Flipping `true → false` is one-way: previously mirrored keys remain in
    * `process.env` until the process exits.
+   * @see {@link https://envapt.materwelon.dev/docs/configuration#mirroring-to-processenv}
    */
   static set syncProcessEnv(value: boolean);
   static get syncProcessEnv(): boolean;
@@ -37,6 +40,7 @@ declare abstract class EnvapterBase {
    * `envFileOptions`, `configureProfiles`, `resetProfiles`). `'warn'` (the default) warns once and
    * no-ops, `'throw'` throws {@link EnvaptError} `FileApiUnsupported`. The node build runs these
    * APIs normally and this value has no effect there.
+   * @see {@link https://envapt.materwelon.dev/docs/compatibility#binding-by-runtime}
    */
   static set fileApiMode(mode: FileApiMode);
   static get fileApiMode(): FileApiMode;
@@ -44,16 +48,20 @@ declare abstract class EnvapterBase {
    * Eagerly load the `.env` cascade now instead of lazily on the first read. Idempotent: a no-op
    * once the cache is built. Useful before mirroring to `process.env` (see {@link syncProcessEnv}),
    * which is what the `envapt/config` side-effect entry does.
+   * @see {@link https://envapt.materwelon.dev/docs/configuration#which-files-load}
    */
   static load(): void;
   /**
    * Bind the environment {@link Source}. On Node the entry binds {@link FileSource} for you
    * (a `process.env` snapshot plus the `.env` cascade). On the browser or Workers, pass a
-   * `PortableSource` (or any `Source`) before reading. Clears and rebuilds the cache.
+   * `PortableSource` (or any `Source`) before reading. Pass a `(key) => string | undefined` reader for
+   * a source that reads one key at a time and cannot list its keys. Clears and rebuilds the cache.
+   * @see {@link https://envapt.materwelon.dev/docs/sources#the-providers}
    */
-  static useSource(source: Source): void;
+  static useSource(source: Source | ((key: string) => string | undefined)): void;
   /**
    * Read an environment variable as its raw string, skipping parsing and conversion.
+   * @see {@link https://envapt.materwelon.dev/docs/envapter#raw-values}
    */
   getRaw(key: EnvKeyInput): string | undefined;
 }

package/dist/types/core/Environment.d.mts

@@ -2,13 +2,14 @@
 /**
  * Environment types supported by Envapter
  *
- * The following keys are checked in order until the first with a non-empty value is found, or defaulting to development if none are set:
+ * The following keys are checked in order until the first with a present (non-missing) value, defaulting to development if none are set:
  * - `ENVIRONMENT`
  * - `ENV`
  * - `NODE_ENV`
  * - `MODE`
  *
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/environment#detecting-the-environment}
  */
 declare enum Environment {
   /** The default when no environment variable names a known environment. */

package/dist/types/core/EnvironmentMethods.d.mts

@@ -9,10 +9,12 @@ import { EnvapterBase } from "./EnvapterBase.mjs";
 declare class EnvironmentMethods extends EnvapterBase {
   /**
    * Get the current application environment
+   * @see {@link https://envapt.materwelon.dev/docs/environment#detecting-the-environment}
    */
   static get environment(): Environment;
   /**
    * Set the application environment. Accepts either Environment enum or string value.
+   * @see {@link https://envapt.materwelon.dev/docs/environment#detecting-the-environment}
    */
   static set environment(env: string | Environment);
   /**
@@ -25,6 +27,7 @@ declare class EnvironmentMethods extends EnvapterBase {
   set environment(env: string | Environment);
   /**
    * Check if the current environment is production
+   * @see {@link https://envapt.materwelon.dev/docs/environment#branching-on-the-environment}
    */
   static get isProduction(): boolean;
   /**
@@ -33,6 +36,7 @@ declare class EnvironmentMethods extends EnvapterBase {
   get isProduction(): boolean;
   /**
    * Check if the current environment is staging
+   * @see {@link https://envapt.materwelon.dev/docs/environment#branching-on-the-environment}
    */
   static get isStaging(): boolean;
   /**
@@ -41,6 +45,7 @@ declare class EnvironmentMethods extends EnvapterBase {
   get isStaging(): boolean;
   /**
    * Check if the current environment is development
+   * @see {@link https://envapt.materwelon.dev/docs/environment#branching-on-the-environment}
    */
   static get isDevelopment(): boolean;
   /**
@@ -49,6 +54,7 @@ declare class EnvironmentMethods extends EnvapterBase {
   get isDevelopment(): boolean;
   /**
    * Check if the current environment is test
+   * @see {@link https://envapt.materwelon.dev/docs/environment#branching-on-the-environment}
    */
   static get isTest(): boolean;
   /**

package/dist/types/core/PrimitiveMethods.d.mts

@@ -11,6 +11,7 @@ declare class PrimitiveMethods extends EnvironmentMethods {
    * Get a string environment variable with optional fallback.
    * Supports template variable resolution using `${VAR}` syntax.
    * Accepts a single key or an ordered array of keys (first match wins).
+   * @see {@link https://envapt.materwelon.dev/docs/envapter#primitives}
    */
   static get<Default extends string | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<string, Default>;
   /**
@@ -21,6 +22,7 @@ declare class PrimitiveMethods extends EnvironmentMethods {
    * Get a number environment variable with optional fallback.
    * Automatically converts string values to numbers.
    * Accepts a single key or an ordered array of keys (first match wins).
+   * @see {@link https://envapt.materwelon.dev/docs/envapter#primitives}
    */
   static getNumber<Default extends number | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<number, Default>;
   /**
@@ -31,6 +33,7 @@ declare class PrimitiveMethods extends EnvironmentMethods {
    * Get a boolean environment variable with optional fallback.
    * Recognizes: `1`, `yes`, `true`, `on` as **true**; `0`, `no`, `false`, `off` as **false** (case-insensitive).
    * Accepts a single key or an ordered array of keys (first match wins).
+   * @see {@link https://envapt.materwelon.dev/docs/envapter#primitives}
    */
   static getBoolean<Default extends boolean | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<boolean, Default>;
   /**
@@ -41,6 +44,7 @@ declare class PrimitiveMethods extends EnvironmentMethods {
    * Get a bigint environment variable with optional fallback.
    * Automatically converts string values to bigint.
    * Accepts a single key or an ordered array of keys (first match wins).
+   * @see {@link https://envapt.materwelon.dev/docs/envapter#primitives}
    */
   static getBigInt<Default extends bigint | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<bigint, Default>;
   /**
@@ -51,6 +55,7 @@ declare class PrimitiveMethods extends EnvironmentMethods {
    * Get a symbol environment variable with optional fallback.
    * Creates a symbol from the string value.
    * Accepts a single key or an ordered array of keys (first match wins).
+   * @see {@link https://envapt.materwelon.dev/docs/envapter#primitives}
    */
   static getSymbol<Default extends symbol | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<symbol, Default>;
   /**

package/dist/types/decorators/legacy/SugarDecorators.d.mts

@@ -6,18 +6,21 @@ import { EnvaptFieldDecorator } from "../../types/Decorator.mjs";
 /**
  * Shorthand for `@Envapt(key, { converter: Converters.Boolean, fallback })`.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/decorators#shorthand-decorators}
  */
 declare function EnvBool(key: EnvKeyInput, fallback: boolean): EnvaptFieldDecorator<boolean>;
 declare function EnvBool(key: EnvKeyInput): EnvaptFieldDecorator<boolean | null>;
 /**
  * Shorthand for `@Envapt(key, { converter: Converters.Number, fallback })`.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/decorators#shorthand-decorators}
  */
 declare function EnvNum(key: EnvKeyInput, fallback: number): EnvaptFieldDecorator<number>;
 declare function EnvNum(key: EnvKeyInput): EnvaptFieldDecorator<number | null>;
 /**
  * Shorthand for `@Envapt(key, { converter: Converters.String, fallback })`.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/decorators#shorthand-decorators}
  */
 declare function EnvStr(key: EnvKeyInput, fallback: string): EnvaptFieldDecorator<string>;
 declare function EnvStr(key: EnvKeyInput): EnvaptFieldDecorator<string | null>;
@@ -25,6 +28,7 @@ declare function EnvStr(key: EnvKeyInput): EnvaptFieldDecorator<string | null>;
  * Shorthand for `@Envapt(key, { converter: Converters.Time, fallback })`. The fallback is a
  * millisecond number or a time string (`'15m'`), and the resolved value is always milliseconds.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/decorators#shorthand-decorators}
  */
 declare function EnvTime(key: EnvKeyInput, fallback: TimeFallback): EnvaptFieldDecorator<number>;
 declare function EnvTime(key: EnvKeyInput): EnvaptFieldDecorator<number | null>;
@@ -32,6 +36,7 @@ declare function EnvTime(key: EnvKeyInput): EnvaptFieldDecorator<number | null>;
  * Shorthand for `@Envapt(key, { converter: Converters.Url, fallback })`. The fallback is a `URL`
  * instance, not a URL string.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/decorators#shorthand-decorators}
  */
 declare function EnvUrl(key: EnvKeyInput, fallback: URL): EnvaptFieldDecorator<URL>;
 declare function EnvUrl(key: EnvKeyInput): EnvaptFieldDecorator<URL | null>;

package/dist/types/decorators/modern/SugarDecorators.d.mts

@@ -6,18 +6,21 @@ import { EnvaptAccessorDecorator } from "../../types/Decorator.mjs";
 /**
  * Shorthand for `@Envapt(key, { converter: Converters.Boolean, fallback })`.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/decorators#shorthand-decorators}
  */
 declare function EnvBool(key: EnvKeyInput, fallback: boolean): EnvaptAccessorDecorator<boolean>;
 declare function EnvBool(key: EnvKeyInput): EnvaptAccessorDecorator<boolean | null>;
 /**
  * Shorthand for `@Envapt(key, { converter: Converters.Number, fallback })`.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/decorators#shorthand-decorators}
  */
 declare function EnvNum(key: EnvKeyInput, fallback: number): EnvaptAccessorDecorator<number>;
 declare function EnvNum(key: EnvKeyInput): EnvaptAccessorDecorator<number | null>;
 /**
  * Shorthand for `@Envapt(key, { converter: Converters.String, fallback })`.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/decorators#shorthand-decorators}
  */
 declare function EnvStr(key: EnvKeyInput, fallback: string): EnvaptAccessorDecorator<string>;
 declare function EnvStr(key: EnvKeyInput): EnvaptAccessorDecorator<string | null>;
@@ -25,6 +28,7 @@ declare function EnvStr(key: EnvKeyInput): EnvaptAccessorDecorator<string | null
  * Shorthand for `@Envapt(key, { converter: Converters.Time, fallback })`. The fallback is a
  * millisecond number or a time string (`'15m'`), and the resolved value is always milliseconds.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/decorators#shorthand-decorators}
  */
 declare function EnvTime(key: EnvKeyInput, fallback: TimeFallback): EnvaptAccessorDecorator<number>;
 declare function EnvTime(key: EnvKeyInput): EnvaptAccessorDecorator<number | null>;
@@ -32,6 +36,7 @@ declare function EnvTime(key: EnvKeyInput): EnvaptAccessorDecorator<number | nul
  * Shorthand for `@Envapt(key, { converter: Converters.Url, fallback })`. The fallback is a `URL`
  * instance, not a URL string.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/decorators#shorthand-decorators}
  */
 declare function EnvUrl(key: EnvKeyInput, fallback: URL): EnvaptAccessorDecorator<URL>;
 declare function EnvUrl(key: EnvKeyInput): EnvaptAccessorDecorator<URL | null>;

package/dist/types/engine/Envapter.d.mts

@@ -40,6 +40,7 @@ declare class Envapter extends AdvancedMethods {
    * const message = Envapter.resolve`Service endpoint: ${'API_URL'}`;
    * // Returns: "Service endpoint: https://api.example.com:8080"
    * ```
+   * @see {@link https://envapt.materwelon.dev/docs/templates#the-resolve-tagged-template}
    */
   static resolve(strings: TemplateStringsArray, ...keys: string[]): string;
   /**
@@ -47,8 +48,9 @@ declare class Envapter extends AdvancedMethods {
    */
   resolve(strings: TemplateStringsArray, ...keys: string[]): string;
   /**
-   * Assert that one or more environment variables are present and non-empty (post-trim,
-   * after template resolution). Throws `MissingEnvValue` listing every missing key.
+   * Assert that one or more environment variables are present and non-empty after template
+   * resolution. Throws `MissingEnvValue` listing every missing key. A whitespace-only value
+   * counts as missing only under strict mode.
    *
    * For a typed required read in functional code, use `Envapter.getRequired(key, converter)`.
    *