envapt 7.1.0 → 8.0.0-next.0

package/dist/node/core/engine.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.cjs","names":["EnvaptError","state","resolveEffectivePaths","loadDotenv","cache","parseEnvironment","firstEnvKeyValue","ENV_KEYS","TemplateResolver","ValueConverter","BuiltInConverters"],"sources":["../../../src/core/engine.ts"],"sourcesContent":["import { BuiltInConverters, ValueConverter } from '../converters';\nimport { ENV_KEYS, Environment, firstEnvKeyValue, parseEnvironment } from './Environment';\nimport { resolveEffectivePaths } from './paths';\nimport { cache, state } from './state';\nimport { TemplateResolver } from '../engine/TemplateResolver';\nimport { debugVerbose, debugWarn } from '../infra/Debug';\nimport { loadDotenv } from '../infra/Dotenv';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { ConditionalReturn, EnvKeyInput } from '../types';\nimport type { EnvapterService } from '../types/Env';\n\nexport function resolveKeyInput(keyInput: EnvKeyInput): { key: string; value: string | undefined } {\n    const keys = Array.isArray(keyInput) ? keyInput : [keyInput];\n    const normalizedKeys = keys as readonly string[];\n\n    if (normalizedKeys.length === 0) {\n        throw new EnvaptError(EnvaptErrorCodes.InvalidKeyInput, 'At least one environment key must be provided.');\n    }\n\n    if (normalizedKeys.some((k) => typeof k !== 'string')) {\n        throw new EnvaptError(EnvaptErrorCodes.InvalidKeyInput, 'Environment keys must be strings.');\n    }\n\n    if (normalizedKeys.some((k) => k.trim() === '')) {\n        throw new EnvaptError(EnvaptErrorCodes.InvalidKeyInput, 'Environment keys cannot be empty strings.');\n    }\n\n    for (const candidate of normalizedKeys) {\n        const value = ensureLoaded().get(candidate) as string | undefined;\n        if (value !== undefined) return { key: candidate, value };\n    }\n\n    return { key: normalizedKeys[0] as string, value: undefined };\n}\n\nexport function treatAsMissing(value: string | undefined): boolean {\n    if (value === undefined || value === '') return true;\n    if (state.strict && value.trim() === '') return true;\n    return false;\n}\n\nexport function ensureLoaded(): Map<string, unknown> {\n    if (!state.cacheBuilt) {\n        const source = state.source;\n        // Clone so the loader and downstream reads never mutate the source's backing object.\n        const isolatedEnv: Record<string, string> = { ...source.readVars() };\n\n        let added = new Set<string>();\n        // Sources without a filesystem (injected objects on the browser or Workers) skip the .env\n        // cascade, profiles, and envPaths. Only the readVars() snapshot populates the cache.\n        if (source.supportsFiles) {\n            debugVerbose(`base dir: ${state.baseDir ?? 'working directory'}`);\n            // Outside the try below so a missing configured profile path surfaces its EnvaptError. Only dotenv parse errors stay caught.\n            const effectivePaths = resolveEffectivePaths();\n            debugVerbose(`effective .env paths: ${effectivePaths.length === 0 ? '(none)' : effectivePaths.join(', ')}`);\n            try {\n                added = loadDotenv({\n                    ...state.userDefinedEnvFileOptions,\n                    path: effectivePaths,\n                    processEnv: isolatedEnv,\n                    readFile: source.readFile.bind(source)\n                });\n            } catch (error) {\n                debugWarn(`failed to load .env: ${error instanceof Error ? error.message : String(error)}`);\n            }\n        }\n        state.dotenvAddedKeys = added;\n        for (const [key, value] of Object.entries(isolatedEnv)) cache.set(key, value);\n        debugVerbose(`cache populated: ${cache.size} keys total`);\n        // set before mirroring, whose template expansion reads the cache and would re-enter this build otherwise\n        state.cacheBuilt = true;\n        if (state.syncProcessEnv) mirrorToProcessEnv();\n    }\n\n    return cache;\n}\n\nexport function refreshCache(): void {\n    // Reset an inferred environment so re-hydration re-determines it from current state. An explicit\n    // Envapter.environment = X is preserved through the refresh and used for cascade selection.\n    if (!state.environmentExplicitlySet) state.environment = undefined;\n    cache.clear();\n    state.cacheBuilt = false;\n    state.dotenvAddedKeys = new Set<string>();\n    debugVerbose('cache cleared, reloading config');\n    ensureLoaded();\n}\n\nexport function mirrorToProcessEnv(): void {\n    if (state.dotenvAddedKeys.size === 0) return;\n    const source = state.source;\n    /* v8 ignore next -- @preserve dotenv keys only accumulate under a file source, so the delta implies supportsFiles here */\n    if (!source.supportsFiles) return;\n    const mirrored: Record<string, string> = {};\n    for (const key of state.dotenvAddedKeys) {\n        const value = cache.get(key);\n        /* v8 ignore next -- @preserve loader only writes strings, defensive against future cache contents */\n        if (typeof value !== 'string') continue;\n        mirrored[key] = resolveForMirror(key, value);\n        debugVerbose(`mirrored ${key} to the ambient environment`);\n    }\n    source.writeVars(mirrored);\n    debugVerbose(`mirrored ${state.dotenvAddedKeys.size} keys to the ambient environment`);\n}\n\nfunction resolveForMirror(key: string, value: string): string {\n    return templateResolver.resolveTemplate(key, value);\n}\n\nexport function determineEnvironment(env?: string | Environment): void {\n    if (typeof env === 'number') {\n        state.environment = env;\n        state.environmentExplicitlySet = true;\n        return;\n    }\n    if (typeof env === 'string') {\n        state.environment = parseEnvironment(env) ?? Environment.Development;\n        state.environmentExplicitlySet = true;\n        return;\n    }\n\n    const raw = firstEnvKeyValue((key) => {\n        const value = ensureLoaded().get(key);\n        return typeof value === 'string' ? value : undefined;\n    });\n    if (raw === undefined) {\n        debugWarn(`no environment set (looked for ${ENV_KEYS.join(', ')}); defaulting to development`);\n        state.environment = Environment.Development;\n        return;\n    }\n    const parsed = parseEnvironment(raw);\n    if (parsed === undefined) {\n        debugWarn(`unrecognized environment \"${raw}\"; defaulting to development`);\n        state.environment = Environment.Development;\n        return;\n    }\n    state.environment = parsed;\n}\n\n/**\n * @internal\n */\nexport enum Primitive {\n    String,\n    Number,\n    Boolean,\n    BigInt,\n    Symbol\n}\n\n// getRaw is the raw string lookup, get is the template-resolved string read. Lazy arrows so the\n// resolver singletons below store envService without calling readPrimitive, which reads\n// templateResolver before it is assigned.\nconst envService: EnvapterService = {\n    getRaw: (key) => resolveKeyInput(key).value,\n    get: (key, def) => readPrimitive<string, string | undefined>(key, Primitive.String, def)\n};\n\nexport const templateResolver: TemplateResolver = new TemplateResolver(envService);\nexport const valueConverter: ValueConverter = new ValueConverter(envService);\n\nexport function readPrimitive<EnvVarReturnType, DefaultType extends EnvVarReturnType | undefined = undefined>(\n    key: EnvKeyInput,\n    type: Primitive,\n    def?: DefaultType\n): ConditionalReturn<EnvVarReturnType, DefaultType> {\n    const { key: resolvedKey, value } = resolveKeyInput(key);\n    if (treatAsMissing(value)) {\n        if (def !== undefined) debugWarn(`${resolvedKey} is missing or empty, using fallback ${String(def)}`);\n        else debugWarn(`${resolvedKey} is missing or empty`);\n        return def as ConditionalReturn<EnvVarReturnType, DefaultType>;\n    }\n\n    const parsed = templateResolver.resolveTemplate(resolvedKey, String(value));\n\n    let result: EnvVarReturnType;\n    if (type === Primitive.Number) result = BuiltInConverters.number(parsed, def as number) as EnvVarReturnType;\n    else if (type === Primitive.Boolean) result = BuiltInConverters.boolean(parsed, def as boolean) as EnvVarReturnType;\n    else if (type === Primitive.BigInt) result = BuiltInConverters.bigint(parsed, def as bigint) as EnvVarReturnType;\n    else if (type === Primitive.Symbol) result = BuiltInConverters.symbol(parsed, def as symbol) as EnvVarReturnType;\n    else result = BuiltInConverters.string(parsed, def as string) as EnvVarReturnType;\n\n    return result;\n}\n"],"mappings":"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"}

package/dist/node/core/engine.mjs

@@ -0,0 +1,2 @@
+import{ENV_KEYS as e,firstEnvKeyValue as t,parseEnvironment as n}from"./Environment.mjs";import{EnvaptError as r}from"../infra/Error.mjs";import{BuiltInConverters as i}from"../converters/BuiltInConverters.mjs";import{cache as a,state as o}from"./state.mjs";import{ValueConverter as s}from"../converters/ValueConverter.mjs";import{resolveEffectivePaths as c}from"./paths.mjs";import{debugVerbose as l,debugWarn as u}from"../infra/Debug.mjs";import{TemplateResolver as d}from"../engine/TemplateResolver.mjs";import{loadDotenv as f}from"../infra/Dotenv.mjs";function p(e){let t=Array.isArray(e)?e:[e];if(t.length===0)throw new r(304,`At least one environment key must be provided.`);if(t.some(e=>typeof e!=`string`))throw new r(304,`Environment keys must be strings.`);if(t.some(e=>e.trim()===``))throw new r(304,`Environment keys cannot be empty strings.`);for(let e of t){let t=h().get(e);if(t!==void 0)return{key:e,value:t}}return{key:t[0],value:void 0}}function m(e){return!!(e===void 0||e===``||o.strict&&e.trim()===``)}function h(){if(!o.cacheBuilt){let e=o.source,t={...e.readVars()},n=new Set;if(e.supportsFiles){l(`base dir: ${o.baseDir??`working directory`}`);let r=c();l(`effective .env paths: ${r.length===0?`(none)`:r.join(`, `)}`);try{n=f({...o.userDefinedEnvFileOptions,path:r,processEnv:t,readFile:e.readFile.bind(e)})}catch(e){u(`failed to load .env: ${e instanceof Error?e.message:String(e)}`)}}o.dotenvAddedKeys=n;for(let[e,n]of Object.entries(t))a.set(e,n);l(`cache populated: ${a.size} keys total`),o.cacheBuilt=!0,o.syncProcessEnv&&_()}return a}function g(){o.environmentExplicitlySet||(o.environment=void 0),a.clear(),o.cacheBuilt=!1,o.dotenvAddedKeys=new Set,l(`cache cleared, reloading config`),h()}function _(){if(o.dotenvAddedKeys.size===0)return;let e=o.source;if(!e.supportsFiles)return;let t={};for(let e of o.dotenvAddedKeys){let n=a.get(e);typeof n==`string`&&(t[e]=v(e,n),l(`mirrored ${e} to the ambient environment`))}e.writeVars(t),l(`mirrored ${o.dotenvAddedKeys.size} keys to the ambient environment`)}function v(e,t){return x.resolveTemplate(e,t)}function y(r){if(typeof r==`number`){o.environment=r,o.environmentExplicitlySet=!0;return}if(typeof r==`string`){o.environment=n(r)??0,o.environmentExplicitlySet=!0;return}let i=t(e=>{let t=h().get(e);return typeof t==`string`?t:void 0});if(i===void 0){u(`no environment set (looked for ${e.join(`, `)}); defaulting to development`),o.environment=0;return}let a=n(i);if(a===void 0){u(`unrecognized environment "${i}"; defaulting to development`),o.environment=0;return}o.environment=a}const b={getRaw:e=>p(e).value,get:(e,t)=>C(e,0,t)},x=new d(b),S=new s(b);function C(e,t,n){let{key:r,value:a}=p(e);if(m(a))return u(n===void 0?`${r} is missing or empty`:`${r} is missing or empty, using fallback ${String(n)}`),n;let o=x.resolveTemplate(r,String(a)),s;return s=t===1?i.number(o,n):t===2?i.boolean(o,n):t===3?i.bigint(o,n):t===4?i.symbol(o,n):i.string(o,n),s}export{y as determineEnvironment,h as ensureLoaded,_ as mirrorToProcessEnv,C as readPrimitive,g as refreshCache,p as resolveKeyInput,x as templateResolver,m as treatAsMissing,S as valueConverter};
+//# sourceMappingURL=engine.mjs.map

package/dist/node/core/engine.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.mjs","names":[],"sources":["../../../src/core/engine.ts"],"sourcesContent":["import { BuiltInConverters, ValueConverter } from '../converters';\nimport { ENV_KEYS, Environment, firstEnvKeyValue, parseEnvironment } from './Environment';\nimport { resolveEffectivePaths } from './paths';\nimport { cache, state } from './state';\nimport { TemplateResolver } from '../engine/TemplateResolver';\nimport { debugVerbose, debugWarn } from '../infra/Debug';\nimport { loadDotenv } from '../infra/Dotenv';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { ConditionalReturn, EnvKeyInput } from '../types';\nimport type { EnvapterService } from '../types/Env';\n\nexport function resolveKeyInput(keyInput: EnvKeyInput): { key: string; value: string | undefined } {\n    const keys = Array.isArray(keyInput) ? keyInput : [keyInput];\n    const normalizedKeys = keys as readonly string[];\n\n    if (normalizedKeys.length === 0) {\n        throw new EnvaptError(EnvaptErrorCodes.InvalidKeyInput, 'At least one environment key must be provided.');\n    }\n\n    if (normalizedKeys.some((k) => typeof k !== 'string')) {\n        throw new EnvaptError(EnvaptErrorCodes.InvalidKeyInput, 'Environment keys must be strings.');\n    }\n\n    if (normalizedKeys.some((k) => k.trim() === '')) {\n        throw new EnvaptError(EnvaptErrorCodes.InvalidKeyInput, 'Environment keys cannot be empty strings.');\n    }\n\n    for (const candidate of normalizedKeys) {\n        const value = ensureLoaded().get(candidate) as string | undefined;\n        if (value !== undefined) return { key: candidate, value };\n    }\n\n    return { key: normalizedKeys[0] as string, value: undefined };\n}\n\nexport function treatAsMissing(value: string | undefined): boolean {\n    if (value === undefined || value === '') return true;\n    if (state.strict && value.trim() === '') return true;\n    return false;\n}\n\nexport function ensureLoaded(): Map<string, unknown> {\n    if (!state.cacheBuilt) {\n        const source = state.source;\n        // Clone so the loader and downstream reads never mutate the source's backing object.\n        const isolatedEnv: Record<string, string> = { ...source.readVars() };\n\n        let added = new Set<string>();\n        // Sources without a filesystem (injected objects on the browser or Workers) skip the .env\n        // cascade, profiles, and envPaths. Only the readVars() snapshot populates the cache.\n        if (source.supportsFiles) {\n            debugVerbose(`base dir: ${state.baseDir ?? 'working directory'}`);\n            // Outside the try below so a missing configured profile path surfaces its EnvaptError. Only dotenv parse errors stay caught.\n            const effectivePaths = resolveEffectivePaths();\n            debugVerbose(`effective .env paths: ${effectivePaths.length === 0 ? '(none)' : effectivePaths.join(', ')}`);\n            try {\n                added = loadDotenv({\n                    ...state.userDefinedEnvFileOptions,\n                    path: effectivePaths,\n                    processEnv: isolatedEnv,\n                    readFile: source.readFile.bind(source)\n                });\n            } catch (error) {\n                debugWarn(`failed to load .env: ${error instanceof Error ? error.message : String(error)}`);\n            }\n        }\n        state.dotenvAddedKeys = added;\n        for (const [key, value] of Object.entries(isolatedEnv)) cache.set(key, value);\n        debugVerbose(`cache populated: ${cache.size} keys total`);\n        // set before mirroring, whose template expansion reads the cache and would re-enter this build otherwise\n        state.cacheBuilt = true;\n        if (state.syncProcessEnv) mirrorToProcessEnv();\n    }\n\n    return cache;\n}\n\nexport function refreshCache(): void {\n    // Reset an inferred environment so re-hydration re-determines it from current state. An explicit\n    // Envapter.environment = X is preserved through the refresh and used for cascade selection.\n    if (!state.environmentExplicitlySet) state.environment = undefined;\n    cache.clear();\n    state.cacheBuilt = false;\n    state.dotenvAddedKeys = new Set<string>();\n    debugVerbose('cache cleared, reloading config');\n    ensureLoaded();\n}\n\nexport function mirrorToProcessEnv(): void {\n    if (state.dotenvAddedKeys.size === 0) return;\n    const source = state.source;\n    /* v8 ignore next -- @preserve dotenv keys only accumulate under a file source, so the delta implies supportsFiles here */\n    if (!source.supportsFiles) return;\n    const mirrored: Record<string, string> = {};\n    for (const key of state.dotenvAddedKeys) {\n        const value = cache.get(key);\n        /* v8 ignore next -- @preserve loader only writes strings, defensive against future cache contents */\n        if (typeof value !== 'string') continue;\n        mirrored[key] = resolveForMirror(key, value);\n        debugVerbose(`mirrored ${key} to the ambient environment`);\n    }\n    source.writeVars(mirrored);\n    debugVerbose(`mirrored ${state.dotenvAddedKeys.size} keys to the ambient environment`);\n}\n\nfunction resolveForMirror(key: string, value: string): string {\n    return templateResolver.resolveTemplate(key, value);\n}\n\nexport function determineEnvironment(env?: string | Environment): void {\n    if (typeof env === 'number') {\n        state.environment = env;\n        state.environmentExplicitlySet = true;\n        return;\n    }\n    if (typeof env === 'string') {\n        state.environment = parseEnvironment(env) ?? Environment.Development;\n        state.environmentExplicitlySet = true;\n        return;\n    }\n\n    const raw = firstEnvKeyValue((key) => {\n        const value = ensureLoaded().get(key);\n        return typeof value === 'string' ? value : undefined;\n    });\n    if (raw === undefined) {\n        debugWarn(`no environment set (looked for ${ENV_KEYS.join(', ')}); defaulting to development`);\n        state.environment = Environment.Development;\n        return;\n    }\n    const parsed = parseEnvironment(raw);\n    if (parsed === undefined) {\n        debugWarn(`unrecognized environment \"${raw}\"; defaulting to development`);\n        state.environment = Environment.Development;\n        return;\n    }\n    state.environment = parsed;\n}\n\n/**\n * @internal\n */\nexport enum Primitive {\n    String,\n    Number,\n    Boolean,\n    BigInt,\n    Symbol\n}\n\n// getRaw is the raw string lookup, get is the template-resolved string read. Lazy arrows so the\n// resolver singletons below store envService without calling readPrimitive, which reads\n// templateResolver before it is assigned.\nconst envService: EnvapterService = {\n    getRaw: (key) => resolveKeyInput(key).value,\n    get: (key, def) => readPrimitive<string, string | undefined>(key, Primitive.String, def)\n};\n\nexport const templateResolver: TemplateResolver = new TemplateResolver(envService);\nexport const valueConverter: ValueConverter = new ValueConverter(envService);\n\nexport function readPrimitive<EnvVarReturnType, DefaultType extends EnvVarReturnType | undefined = undefined>(\n    key: EnvKeyInput,\n    type: Primitive,\n    def?: DefaultType\n): ConditionalReturn<EnvVarReturnType, DefaultType> {\n    const { key: resolvedKey, value } = resolveKeyInput(key);\n    if (treatAsMissing(value)) {\n        if (def !== undefined) debugWarn(`${resolvedKey} is missing or empty, using fallback ${String(def)}`);\n        else debugWarn(`${resolvedKey} is missing or empty`);\n        return def as ConditionalReturn<EnvVarReturnType, DefaultType>;\n    }\n\n    const parsed = templateResolver.resolveTemplate(resolvedKey, String(value));\n\n    let result: EnvVarReturnType;\n    if (type === Primitive.Number) result = BuiltInConverters.number(parsed, def as number) as EnvVarReturnType;\n    else if (type === Primitive.Boolean) result = BuiltInConverters.boolean(parsed, def as boolean) as EnvVarReturnType;\n    else if (type === Primitive.BigInt) result = BuiltInConverters.bigint(parsed, def as bigint) as EnvVarReturnType;\n    else if (type === Primitive.Symbol) result = BuiltInConverters.symbol(parsed, def as symbol) as EnvVarReturnType;\n    else result = BuiltInConverters.string(parsed, def as string) as EnvVarReturnType;\n\n    return result;\n}\n"],"mappings":"2iBAYA,SAAgB,EAAgB,EAAmE,CAE/F,IAAM,EADO,MAAM,QAAQ,CAAQ,EAAI,EAAW,CAAC,CAAQ,EAG3D,GAAI,EAAe,SAAW,EAC1B,MAAM,IAAI,EAAA,IAA8C,gDAAgD,EAG5G,GAAI,EAAe,KAAM,GAAM,OAAO,GAAM,QAAQ,EAChD,MAAM,IAAI,EAAA,IAA8C,mCAAmC,EAG/F,GAAI,EAAe,KAAM,GAAM,EAAE,KAAK,IAAM,EAAE,EAC1C,MAAM,IAAI,EAAA,IAA8C,2CAA2C,EAGvG,IAAK,IAAM,KAAa,EAAgB,CACpC,IAAM,EAAQ,EAAa,CAAC,CAAC,IAAI,CAAS,EAC1C,GAAI,IAAU,IAAA,GAAW,MAAO,CAAE,IAAK,EAAW,OAAM,CAC5D,CAEA,MAAO,CAAE,IAAK,EAAe,GAAc,MAAO,IAAA,EAAU,CAChE,CAEA,SAAgB,EAAe,EAAoC,CAG/D,MADA,GADI,IAAU,IAAA,IAAa,IAAU,IACjC,EAAM,QAAU,EAAM,KAAK,IAAM,GAEzC,CAEA,SAAgB,GAAqC,CACjD,GAAI,CAAC,EAAM,WAAY,CACnB,IAAM,EAAS,EAAM,OAEf,EAAsC,CAAE,GAAG,EAAO,SAAS,CAAE,EAE/D,EAAQ,IAAI,IAGhB,GAAI,EAAO,cAAe,CACtB,EAAa,aAAa,EAAM,SAAW,qBAAqB,EAEhE,IAAM,EAAiB,EAAsB,EAC7C,EAAa,yBAAyB,EAAe,SAAW,EAAI,SAAW,EAAe,KAAK,IAAI,GAAG,EAC1G,GAAI,CACA,EAAQ,EAAW,CACf,GAAG,EAAM,0BACT,KAAM,EACN,WAAY,EACZ,SAAU,EAAO,SAAS,KAAK,CAAM,CACzC,CAAC,CACL,OAAS,EAAO,CACZ,EAAU,wBAAwB,aAAiB,MAAQ,EAAM,QAAU,OAAO,CAAK,GAAG,CAC9F,CACJ,CACA,EAAM,gBAAkB,EACxB,IAAK,GAAM,CAAC,EAAK,KAAU,OAAO,QAAQ,CAAW,EAAG,EAAM,IAAI,EAAK,CAAK,EAC5E,EAAa,oBAAoB,EAAM,KAAK,YAAY,EAExD,EAAM,WAAa,GACf,EAAM,gBAAgB,EAAmB,CACjD,CAEA,OAAO,CACX,CAEA,SAAgB,GAAqB,CAG5B,EAAM,2BAA0B,EAAM,YAAc,IAAA,IACzD,EAAM,MAAM,EACZ,EAAM,WAAa,GACnB,EAAM,gBAAkB,IAAI,IAC5B,EAAa,iCAAiC,EAC9C,EAAa,CACjB,CAEA,SAAgB,GAA2B,CACvC,GAAI,EAAM,gBAAgB,OAAS,EAAG,OACtC,IAAM,EAAS,EAAM,OAErB,GAAI,CAAC,EAAO,cAAe,OAC3B,IAAM,EAAmC,CAAC,EAC1C,IAAK,IAAM,KAAO,EAAM,gBAAiB,CACrC,IAAM,EAAQ,EAAM,IAAI,CAAG,EAEvB,OAAO,GAAU,WACrB,EAAS,GAAO,EAAiB,EAAK,CAAK,EAC3C,EAAa,YAAY,EAAI,4BAA4B,EAC7D,CACA,EAAO,UAAU,CAAQ,EACzB,EAAa,YAAY,EAAM,gBAAgB,KAAK,iCAAiC,CACzF,CAEA,SAAS,EAAiB,EAAa,EAAuB,CAC1D,OAAO,EAAiB,gBAAgB,EAAK,CAAK,CACtD,CAEA,SAAgB,EAAqB,EAAkC,CACnE,GAAI,OAAO,GAAQ,SAAU,CACzB,EAAM,YAAc,EACpB,EAAM,yBAA2B,GACjC,MACJ,CACA,GAAI,OAAO,GAAQ,SAAU,CACzB,EAAM,YAAc,EAAiB,CAAG,GAAA,EACxC,EAAM,yBAA2B,GACjC,MACJ,CAEA,IAAM,EAAM,EAAkB,GAAQ,CAClC,IAAM,EAAQ,EAAa,CAAC,CAAC,IAAI,CAAG,EACpC,OAAO,OAAO,GAAU,SAAW,EAAQ,IAAA,EAC/C,CAAC,EACD,GAAI,IAAQ,IAAA,GAAW,CACnB,EAAU,kCAAkC,EAAS,KAAK,IAAI,EAAE,6BAA6B,EAC7F,EAAM,YAAA,EACN,MACJ,CACA,IAAM,EAAS,EAAiB,CAAG,EACnC,GAAI,IAAW,IAAA,GAAW,CACtB,EAAU,6BAA6B,EAAI,6BAA6B,EACxE,EAAM,YAAA,EACN,MACJ,CACA,EAAM,YAAc,CACxB,CAgBA,MAAM,EAA8B,CAChC,OAAS,GAAQ,EAAgB,CAAG,CAAC,CAAC,MACtC,KAAM,EAAK,IAAQ,EAA0C,EAAA,EAAuB,CAAG,CAC3F,EAEa,EAAqC,IAAI,EAAiB,CAAU,EACpE,EAAiC,IAAI,EAAe,CAAU,EAE3E,SAAgB,EACZ,EACA,EACA,EACgD,CAChD,GAAM,CAAE,IAAK,EAAa,SAAU,EAAgB,CAAG,EACvD,GAAI,EAAe,CAAK,EAGpB,OADK,EADD,IAAQ,IAAA,GACG,GAAG,EAAY,sBADG,GAAG,EAAY,uCAAuC,OAAO,CAAG,GAC9C,EAC5C,EAGX,IAAM,EAAS,EAAiB,gBAAgB,EAAa,OAAO,CAAK,CAAC,EAEtE,EAOJ,MANA,CAIK,EAJD,IAAA,EAAoC,EAAkB,OAAO,EAAQ,CAAa,EAC7E,IAAA,EAAqC,EAAkB,QAAQ,EAAQ,CAAc,EACrF,IAAA,EAAoC,EAAkB,OAAO,EAAQ,CAAa,EAClF,IAAA,EAAoC,EAAkB,OAAO,EAAQ,CAAa,EAC7E,EAAkB,OAAO,EAAQ,CAAa,EAErD,CACX"}

package/dist/node/core/paths.cjs

@@ -0,0 +1,2 @@
+const e=require("./Environment.cjs"),t=require("../infra/Error.cjs"),n=require("./state.cjs");function r(e){let t=n.state.baseDir;if(t===void 0)return e;let r=n.state.source;return r.supportsFiles?r.resolvePath(t,e):e}function i(e,n){if(!n.supportsFiles)throw new t.EnvaptError(306,`${e} requires a filesystem-backed source; the bound source does not support .env files.`)}function a(e){let t=n.state.source;return t.supportsFiles?t.readFile(e,`utf8`)!==void 0:!1}function o(t){let n=e.Environment[t].toLowerCase();return[`.env.${n}.local`,`.env.${n}`,`.env.local`,`.env`].map(e=>r(e)).filter(e=>a(e))}function s(e){return e?Array.isArray(e.paths)?e.paths:[e.paths]:[]}function c(){if(n.state.environment!==void 0)return n.state.environment;let t=n.state.source.readVars(),r=e.firstEnvKeyValue(e=>t[e]);return r===void 0?0:e.parseEnvironment(r)??0}function l(){if(n.state.envPathsExplicitlySet)return n.state.envPaths.map(e=>r(e));let e=c(),i=n.state.profiles?.[e],l=s(i);if(l.length>0){let e=l.filter(e=>!a(r(e)));if(e.length>0)throw new t.EnvaptError(303,`Environment file not found at path: ${e.join(`, `)}`)}let u=n.state.profiles?.useDefaults===!1?[]:o(e);return[...l.map(e=>r(e)),...u]}exports.assertFileApiSupported=i,exports.resolveAgainstBase=r,exports.resolveEffectivePaths=l,exports.sourceFileExists=a;
+//# sourceMappingURL=paths.cjs.map

package/dist/node/core/paths.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.cjs","names":["state","EnvaptError","Environment","firstEnvKeyValue","parseEnvironment"],"sources":["../../../src/core/paths.ts"],"sourcesContent":["import { Environment, firstEnvKeyValue, parseEnvironment } from './Environment';\nimport { state } from './state';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { EnvProfile, FileCapableSource, Source } from '../types';\n\n// No baseDir: candidate returned unchanged so the source resolves it against its own default\n// (process.cwd() on Node). Resolution goes through the source to keep this node-free.\nexport function resolveAgainstBase(candidate: string): string {\n    const baseDir = state.baseDir;\n    if (baseDir === undefined) return candidate;\n    const source = state.source;\n    /* v8 ignore next -- @preserve callers are all file-gated, so the source is never bare here */\n    if (!source.supportsFiles) return candidate;\n    return source.resolvePath(baseDir, candidate);\n}\n\n// File-based config (envPaths/baseDir/configureProfiles) is meaningless without a filesystem, and it\n// throws instead of silently ignoring it on the browser or Workers. Narrows the source so callers\n// can use the file capabilities (resolvePath/normalizeBaseDir) after the check.\nexport function assertFileApiSupported(api: string, source: Source): asserts source is FileCapableSource {\n    if (!source.supportsFiles) {\n        throw new EnvaptError(\n            EnvaptErrorCodes.FileApiUnsupported,\n            `${api} requires a filesystem-backed source; the bound source does not support .env files.`\n        );\n    }\n}\n\n// Existence via the bound source instead of fs.existsSync/accessSync: a file \"exists\" when the source\n// can read it.\nexport function sourceFileExists(path: string): boolean {\n    const source = state.source;\n    /* v8 ignore next -- @preserve every caller is file-gated, so this never sees a bare source */\n    if (!source.supportsFiles) return false;\n    return source.readFile(path, 'utf8') !== undefined;\n}\n\n// Precedence is most-specific-wins (matches Vite / Astro / Vocs): `.env.${env}.local` > `.env.${env}`\n// > `.env.local` > `.env`. This differs from dotenv-flow / Next.js, which put `.env.local` above\n// `.env.${env}`. Most-specific-wins keeps a committed `.env.production` authoritative regardless of a\n// stray `.env.local`. Missing files are filtered.\nfunction buildCascadePaths(env: Environment): string[] {\n    const envName = Environment[env].toLowerCase();\n    return [`.env.${envName}.local`, `.env.${envName}`, '.env.local', '.env']\n        .map((name) => resolveAgainstBase(name))\n        .filter((p) => sourceFileExists(p));\n}\n\nfunction normalizeProfilePaths(profile: EnvProfile | undefined): string[] {\n    if (!profile) return [];\n    return Array.isArray(profile.paths) ? profile.paths : [profile.paths];\n}\n\n// Reads the source's raw vars, not the cache, because cascade selection runs before the `.env` load.\n// `Envapter.environment` may differ post-load if a file sets `ENVIRONMENT`.\nfunction getCascadeEnvironment(): Environment {\n    if (state.environment !== undefined) return state.environment;\n\n    const vars = state.source.readVars();\n    const raw = firstEnvKeyValue((key) => vars[key]);\n    return raw === undefined ? Environment.Development : (parseEnvironment(raw) ?? Environment.Development);\n}\n\n/**\n * Resolve the `.env` paths to load. When `envPaths` was explicitly set, only those load. Otherwise\n * layer any `configureProfiles` paths for the active environment (higher precedence) over the\n * dotenv-flow cascade, all in dotenv first-wins order. `useDefaults: false` drops the cascade.\n */\nexport function resolveEffectivePaths(): string[] {\n    if (state.envPathsExplicitlySet) return state.envPaths.map((p) => resolveAgainstBase(p));\n\n    const env = getCascadeEnvironment();\n    const profileEntry = state.profiles?.[env];\n    const profilePaths = normalizeProfilePaths(profileEntry);\n\n    // Validate that explicitly configured profile paths exist for the active env.\n    if (profilePaths.length > 0) {\n        const missing = profilePaths.filter((p) => !sourceFileExists(resolveAgainstBase(p)));\n        if (missing.length > 0) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.EnvFilesNotFound,\n                `Environment file not found at path: ${missing.join(', ')}`\n            );\n        }\n    }\n\n    const cascade = state.profiles?.useDefaults === false ? [] : buildCascadePaths(env);\n    return [...profilePaths.map((p) => resolveAgainstBase(p)), ...cascade];\n}\n"],"mappings":"8FAQA,SAAgB,EAAmB,EAA2B,CAC1D,IAAM,EAAUA,EAAAA,MAAM,QACtB,GAAI,IAAY,IAAA,GAAW,OAAO,EAClC,IAAM,EAASA,EAAAA,MAAM,OAGrB,OADK,EAAO,cACL,EAAO,YAAY,EAAS,CAAS,EADV,CAEtC,CAKA,SAAgB,EAAuB,EAAa,EAAqD,CACrG,GAAI,CAAC,EAAO,cACR,MAAM,IAAIC,EAAAA,YAAAA,IAEN,GAAG,EAAI,oFACX,CAER,CAIA,SAAgB,EAAiB,EAAuB,CACpD,IAAM,EAASD,EAAAA,MAAM,OAGrB,OADK,EAAO,cACL,EAAO,SAAS,EAAM,MAAM,IAAM,IAAA,GADP,EAEtC,CAMA,SAAS,EAAkB,EAA4B,CACnD,IAAM,EAAUE,EAAAA,YAAY,EAAI,CAAC,YAAY,EAC7C,MAAO,CAAC,QAAQ,EAAQ,QAAS,QAAQ,IAAW,aAAc,MAAM,CAAC,CACpE,IAAK,GAAS,EAAmB,CAAI,CAAC,CAAC,CACvC,OAAQ,GAAM,EAAiB,CAAC,CAAC,CAC1C,CAEA,SAAS,EAAsB,EAA2C,CAEtE,OADK,EACE,MAAM,QAAQ,EAAQ,KAAK,EAAI,EAAQ,MAAQ,CAAC,EAAQ,KAAK,EAD/C,CAAC,CAE1B,CAIA,SAAS,GAAqC,CAC1C,GAAIF,EAAAA,MAAM,cAAgB,IAAA,GAAW,OAAOA,EAAAA,MAAM,YAElD,IAAM,EAAOA,EAAAA,MAAM,OAAO,SAAS,EAC7B,EAAMG,EAAAA,iBAAkB,GAAQ,EAAK,EAAI,EAC/C,OAAO,IAAQ,IAAA,GAAA,EAAuCC,EAAAA,iBAAiB,CAAG,GAAA,CAC9E,CAOA,SAAgB,GAAkC,CAC9C,GAAIJ,EAAAA,MAAM,sBAAuB,OAAOA,EAAAA,MAAM,SAAS,IAAK,GAAM,EAAmB,CAAC,CAAC,EAEvF,IAAM,EAAM,EAAsB,EAC5B,EAAeA,EAAAA,MAAM,WAAW,GAChC,EAAe,EAAsB,CAAY,EAGvD,GAAI,EAAa,OAAS,EAAG,CACzB,IAAM,EAAU,EAAa,OAAQ,GAAM,CAAC,EAAiB,EAAmB,CAAC,CAAC,CAAC,EACnF,GAAI,EAAQ,OAAS,EACjB,MAAM,IAAIC,EAAAA,YAAAA,IAEN,uCAAuC,EAAQ,KAAK,IAAI,GAC5D,CAER,CAEA,IAAM,EAAUD,EAAAA,MAAM,UAAU,cAAgB,GAAQ,CAAC,EAAI,EAAkB,CAAG,EAClF,MAAO,CAAC,GAAG,EAAa,IAAK,GAAM,EAAmB,CAAC,CAAC,EAAG,GAAG,CAAO,CACzE"}

package/dist/node/core/paths.mjs

@@ -0,0 +1,2 @@
+import{Environment as e,firstEnvKeyValue as t,parseEnvironment as n}from"./Environment.mjs";import{EnvaptError as r}from"../infra/Error.mjs";import{state as i}from"./state.mjs";function a(e){let t=i.baseDir;if(t===void 0)return e;let n=i.source;return n.supportsFiles?n.resolvePath(t,e):e}function o(e,t){if(!t.supportsFiles)throw new r(306,`${e} requires a filesystem-backed source; the bound source does not support .env files.`)}function s(e){let t=i.source;return t.supportsFiles?t.readFile(e,`utf8`)!==void 0:!1}function c(t){let n=e[t].toLowerCase();return[`.env.${n}.local`,`.env.${n}`,`.env.local`,`.env`].map(e=>a(e)).filter(e=>s(e))}function l(e){return e?Array.isArray(e.paths)?e.paths:[e.paths]:[]}function u(){if(i.environment!==void 0)return i.environment;let e=i.source.readVars(),r=t(t=>e[t]);return r===void 0?0:n(r)??0}function d(){if(i.envPathsExplicitlySet)return i.envPaths.map(e=>a(e));let e=u(),t=i.profiles?.[e],n=l(t);if(n.length>0){let e=n.filter(e=>!s(a(e)));if(e.length>0)throw new r(303,`Environment file not found at path: ${e.join(`, `)}`)}let o=i.profiles?.useDefaults===!1?[]:c(e);return[...n.map(e=>a(e)),...o]}export{o as assertFileApiSupported,a as resolveAgainstBase,d as resolveEffectivePaths,s as sourceFileExists};
+//# sourceMappingURL=paths.mjs.map

package/dist/node/core/paths.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.mjs","names":[],"sources":["../../../src/core/paths.ts"],"sourcesContent":["import { Environment, firstEnvKeyValue, parseEnvironment } from './Environment';\nimport { state } from './state';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { EnvProfile, FileCapableSource, Source } from '../types';\n\n// No baseDir: candidate returned unchanged so the source resolves it against its own default\n// (process.cwd() on Node). Resolution goes through the source to keep this node-free.\nexport function resolveAgainstBase(candidate: string): string {\n    const baseDir = state.baseDir;\n    if (baseDir === undefined) return candidate;\n    const source = state.source;\n    /* v8 ignore next -- @preserve callers are all file-gated, so the source is never bare here */\n    if (!source.supportsFiles) return candidate;\n    return source.resolvePath(baseDir, candidate);\n}\n\n// File-based config (envPaths/baseDir/configureProfiles) is meaningless without a filesystem, and it\n// throws instead of silently ignoring it on the browser or Workers. Narrows the source so callers\n// can use the file capabilities (resolvePath/normalizeBaseDir) after the check.\nexport function assertFileApiSupported(api: string, source: Source): asserts source is FileCapableSource {\n    if (!source.supportsFiles) {\n        throw new EnvaptError(\n            EnvaptErrorCodes.FileApiUnsupported,\n            `${api} requires a filesystem-backed source; the bound source does not support .env files.`\n        );\n    }\n}\n\n// Existence via the bound source instead of fs.existsSync/accessSync: a file \"exists\" when the source\n// can read it.\nexport function sourceFileExists(path: string): boolean {\n    const source = state.source;\n    /* v8 ignore next -- @preserve every caller is file-gated, so this never sees a bare source */\n    if (!source.supportsFiles) return false;\n    return source.readFile(path, 'utf8') !== undefined;\n}\n\n// Precedence is most-specific-wins (matches Vite / Astro / Vocs): `.env.${env}.local` > `.env.${env}`\n// > `.env.local` > `.env`. This differs from dotenv-flow / Next.js, which put `.env.local` above\n// `.env.${env}`. Most-specific-wins keeps a committed `.env.production` authoritative regardless of a\n// stray `.env.local`. Missing files are filtered.\nfunction buildCascadePaths(env: Environment): string[] {\n    const envName = Environment[env].toLowerCase();\n    return [`.env.${envName}.local`, `.env.${envName}`, '.env.local', '.env']\n        .map((name) => resolveAgainstBase(name))\n        .filter((p) => sourceFileExists(p));\n}\n\nfunction normalizeProfilePaths(profile: EnvProfile | undefined): string[] {\n    if (!profile) return [];\n    return Array.isArray(profile.paths) ? profile.paths : [profile.paths];\n}\n\n// Reads the source's raw vars, not the cache, because cascade selection runs before the `.env` load.\n// `Envapter.environment` may differ post-load if a file sets `ENVIRONMENT`.\nfunction getCascadeEnvironment(): Environment {\n    if (state.environment !== undefined) return state.environment;\n\n    const vars = state.source.readVars();\n    const raw = firstEnvKeyValue((key) => vars[key]);\n    return raw === undefined ? Environment.Development : (parseEnvironment(raw) ?? Environment.Development);\n}\n\n/**\n * Resolve the `.env` paths to load. When `envPaths` was explicitly set, only those load. Otherwise\n * layer any `configureProfiles` paths for the active environment (higher precedence) over the\n * dotenv-flow cascade, all in dotenv first-wins order. `useDefaults: false` drops the cascade.\n */\nexport function resolveEffectivePaths(): string[] {\n    if (state.envPathsExplicitlySet) return state.envPaths.map((p) => resolveAgainstBase(p));\n\n    const env = getCascadeEnvironment();\n    const profileEntry = state.profiles?.[env];\n    const profilePaths = normalizeProfilePaths(profileEntry);\n\n    // Validate that explicitly configured profile paths exist for the active env.\n    if (profilePaths.length > 0) {\n        const missing = profilePaths.filter((p) => !sourceFileExists(resolveAgainstBase(p)));\n        if (missing.length > 0) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.EnvFilesNotFound,\n                `Environment file not found at path: ${missing.join(', ')}`\n            );\n        }\n    }\n\n    const cascade = state.profiles?.useDefaults === false ? [] : buildCascadePaths(env);\n    return [...profilePaths.map((p) => resolveAgainstBase(p)), ...cascade];\n}\n"],"mappings":"iLAQA,SAAgB,EAAmB,EAA2B,CAC1D,IAAM,EAAU,EAAM,QACtB,GAAI,IAAY,IAAA,GAAW,OAAO,EAClC,IAAM,EAAS,EAAM,OAGrB,OADK,EAAO,cACL,EAAO,YAAY,EAAS,CAAS,EADV,CAEtC,CAKA,SAAgB,EAAuB,EAAa,EAAqD,CACrG,GAAI,CAAC,EAAO,cACR,MAAM,IAAI,EAAA,IAEN,GAAG,EAAI,oFACX,CAER,CAIA,SAAgB,EAAiB,EAAuB,CACpD,IAAM,EAAS,EAAM,OAGrB,OADK,EAAO,cACL,EAAO,SAAS,EAAM,MAAM,IAAM,IAAA,GADP,EAEtC,CAMA,SAAS,EAAkB,EAA4B,CACnD,IAAM,EAAU,EAAY,EAAI,CAAC,YAAY,EAC7C,MAAO,CAAC,QAAQ,EAAQ,QAAS,QAAQ,IAAW,aAAc,MAAM,CAAC,CACpE,IAAK,GAAS,EAAmB,CAAI,CAAC,CAAC,CACvC,OAAQ,GAAM,EAAiB,CAAC,CAAC,CAC1C,CAEA,SAAS,EAAsB,EAA2C,CAEtE,OADK,EACE,MAAM,QAAQ,EAAQ,KAAK,EAAI,EAAQ,MAAQ,CAAC,EAAQ,KAAK,EAD/C,CAAC,CAE1B,CAIA,SAAS,GAAqC,CAC1C,GAAI,EAAM,cAAgB,IAAA,GAAW,OAAO,EAAM,YAElD,IAAM,EAAO,EAAM,OAAO,SAAS,EAC7B,EAAM,EAAkB,GAAQ,EAAK,EAAI,EAC/C,OAAO,IAAQ,IAAA,GAAA,EAAuC,EAAiB,CAAG,GAAA,CAC9E,CAOA,SAAgB,GAAkC,CAC9C,GAAI,EAAM,sBAAuB,OAAO,EAAM,SAAS,IAAK,GAAM,EAAmB,CAAC,CAAC,EAEvF,IAAM,EAAM,EAAsB,EAC5B,EAAe,EAAM,WAAW,GAChC,EAAe,EAAsB,CAAY,EAGvD,GAAI,EAAa,OAAS,EAAG,CACzB,IAAM,EAAU,EAAa,OAAQ,GAAM,CAAC,EAAiB,EAAmB,CAAC,CAAC,CAAC,EACnF,GAAI,EAAQ,OAAS,EACjB,MAAM,IAAI,EAAA,IAEN,uCAAuC,EAAQ,KAAK,IAAI,GAC5D,CAER,CAEA,IAAM,EAAU,EAAM,UAAU,cAAgB,GAAQ,CAAC,EAAI,EAAkB,CAAG,EAClF,MAAO,CAAC,GAAG,EAAa,IAAK,GAAM,EAAmB,CAAC,CAAC,EAAG,GAAG,CAAO,CACzE"}

package/dist/node/core/state.cjs

@@ -0,0 +1,2 @@
+const e=require("../sources/UnboundSource.cjs"),t={envPaths:[`.env`],envPathsExplicitlySet:!1,baseDir:void 0,userDefinedEnvFileOptions:{},strict:!1,syncProcessEnv:!1,fileApiMode:`warn`,dotenvAddedKeys:new Set,cacheBuilt:!1,source:new e.UnboundSource,environment:void 0,environmentExplicitlySet:!1,profiles:void 0},n=new Map;exports.cache=n,exports.state=t;
+//# sourceMappingURL=state.cjs.map

package/dist/node/core/state.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.cjs","names":["UnboundSource"],"sources":["../../../src/core/state.ts"],"sourcesContent":["import { UnboundSource } from '../sources/UnboundSource';\n\nimport type { Environment } from './Environment';\nimport type { EnvFileOptions } from '../infra/Dotenv';\nimport type { FileApiMode, ProfilesConfig, Source } from '../types';\n\n// The engine's mutable state that should not be exposed in the package exports map.\nexport const state = {\n    envPaths: ['.env'] as string[],\n    envPathsExplicitlySet: false,\n    baseDir: undefined as string | undefined,\n    userDefinedEnvFileOptions: {} as EnvFileOptions,\n    strict: false,\n    syncProcessEnv: false,\n    fileApiMode: 'warn' as FileApiMode,\n    // loader-written keys only (collisions skipped), refilled on every cache rebuild.\n    dotenvAddedKeys: new Set<string>(),\n    // cache.size can't tell built-and-empty from not-built, so a source resolving to no keys would rebuild on every read without this.\n    cacheBuilt: false,\n    // unbound by default so non-Node builds throw NoSourceBound on read until useSource() runs.\n    source: new UnboundSource() as Source,\n    environment: undefined as Environment | undefined,\n    environmentExplicitlySet: false,\n    profiles: undefined as ProfilesConfig | undefined\n};\n\nexport const cache = new Map<string, unknown>();\n"],"mappings":"gDAOa,EAAQ,CACjB,SAAU,CAAC,MAAM,EACjB,sBAAuB,GACvB,QAAS,IAAA,GACT,0BAA2B,CAAC,EAC5B,OAAQ,GACR,eAAgB,GAChB,YAAa,OAEb,gBAAiB,IAAI,IAErB,WAAY,GAEZ,OAAQ,IAAIA,EAAAA,cACZ,YAAa,IAAA,GACb,yBAA0B,GAC1B,SAAU,IAAA,EACd,EAEa,EAAQ,IAAI"}

package/dist/node/core/state.mjs

@@ -0,0 +1,2 @@
+import{UnboundSource as e}from"../sources/UnboundSource.mjs";const t={envPaths:[`.env`],envPathsExplicitlySet:!1,baseDir:void 0,userDefinedEnvFileOptions:{},strict:!1,syncProcessEnv:!1,fileApiMode:`warn`,dotenvAddedKeys:new Set,cacheBuilt:!1,source:new e,environment:void 0,environmentExplicitlySet:!1,profiles:void 0},n=new Map;export{n as cache,t as state};
+//# sourceMappingURL=state.mjs.map

package/dist/node/core/state.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.mjs","names":[],"sources":["../../../src/core/state.ts"],"sourcesContent":["import { UnboundSource } from '../sources/UnboundSource';\n\nimport type { Environment } from './Environment';\nimport type { EnvFileOptions } from '../infra/Dotenv';\nimport type { FileApiMode, ProfilesConfig, Source } from '../types';\n\n// The engine's mutable state that should not be exposed in the package exports map.\nexport const state = {\n    envPaths: ['.env'] as string[],\n    envPathsExplicitlySet: false,\n    baseDir: undefined as string | undefined,\n    userDefinedEnvFileOptions: {} as EnvFileOptions,\n    strict: false,\n    syncProcessEnv: false,\n    fileApiMode: 'warn' as FileApiMode,\n    // loader-written keys only (collisions skipped), refilled on every cache rebuild.\n    dotenvAddedKeys: new Set<string>(),\n    // cache.size can't tell built-and-empty from not-built, so a source resolving to no keys would rebuild on every read without this.\n    cacheBuilt: false,\n    // unbound by default so non-Node builds throw NoSourceBound on read until useSource() runs.\n    source: new UnboundSource() as Source,\n    environment: undefined as Environment | undefined,\n    environmentExplicitlySet: false,\n    profiles: undefined as ProfilesConfig | undefined\n};\n\nexport const cache = new Map<string, unknown>();\n"],"mappings":"6DAOA,MAAa,EAAQ,CACjB,SAAU,CAAC,MAAM,EACjB,sBAAuB,GACvB,QAAS,IAAA,GACT,0BAA2B,CAAC,EAC5B,OAAQ,GACR,eAAgB,GAChB,YAAa,OAEb,gBAAiB,IAAI,IAErB,WAAY,GAEZ,OAAQ,IAAI,EACZ,YAAa,IAAA,GACb,yBAA0B,GAC1B,SAAU,IAAA,EACd,EAEa,EAAQ,IAAI"}

package/dist/node/decorators/resolveDecoratorValue.cjs

@@ -1,2 +1,2 @@
-const e=require("../infra/Error.cjs"),t=require("../core/EnvapterBase.cjs"),n=require("../converters/ValueConverter.cjs"),r=require("../engine/Envapter.cjs");function i(e){return Array.isArray(e)?`[${e.join(`, `)}]`:String(e)}const a=new WeakMap;let o=0;function s(e,t,n){let r=a.get(e);return r===void 0&&(r=o++,a.set(e,r)),`${r}.${t?`static`:`instance`}.${n}`}function c(a,o,s){let{fallback:c,converter:l,hasFallback:u,required:d,schema:f}=o;if(t.EnvaptCache.has(s))return t.EnvaptCache.get(s);let p=new r.Envapter;if(d&&f===void 0){let t=p.getRaw(a);if(t===void 0||t.trim()===``)throw new e.EnvaptError(305,`Required environment variable "${i(a)}" is missing or empty.`)}let m=new n.ValueConverter(p),h=f===void 0?m.convertValue(a,c,l,u):m.convertWithSchema(a,f,c,u);return t.EnvaptCache.set(s,h),h}exports.decoratorCacheKey=s,exports.resolveDecoratorValue=c;
+const e=require("../infra/Error.cjs"),t=require("../core/state.cjs"),n=require("../converters/ValueConverter.cjs"),r=require("../engine/Envapter.cjs");function i(e){return Array.isArray(e)?`[${e.join(`, `)}]`:String(e)}const a=new WeakMap;let o=0;function s(e,t,n){let r=a.get(e);return r===void 0&&(r=o++,a.set(e,r)),`${r}.${t?`static`:`instance`}.${n}`}function c(a,o,s){let{fallback:c,converter:l,hasFallback:u,required:d,schema:f}=o;if(t.cache.has(s))return t.cache.get(s);let p=new r.Envapter;if(d&&f===void 0){let t=p.getRaw(a);if(t===void 0||t.trim()===``)throw new e.EnvaptError(305,`Required environment variable "${i(a)}" is missing or empty.`)}let m=new n.ValueConverter(p),h=f===void 0?m.convertValue(a,c,l,u):m.convertWithSchema(a,f,c,u);return t.cache.set(s,h),h}exports.decoratorCacheKey=s,exports.resolveDecoratorValue=c;
 //# sourceMappingURL=resolveDecoratorValue.cjs.map

package/dist/node/decorators/resolveDecoratorValue.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"resolveDecoratorValue.cjs","names":["EnvaptCache","Envapter","EnvaptError","ValueConverter"],"sources":["../../../src/decorators/resolveDecoratorValue.ts"],"sourcesContent":["import { ValueConverter } from '../converters';\nimport { EnvaptCache } from '../core';\nimport { Envapter } from '../engine/Envapter';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { StandardSchemaV1 } from '../infra/StandardSchema';\nimport type { EnvaptConverter, EnvKeyInput } from '../types';\n\nexport interface DecoratorConfig<TFallback> {\n    fallback: TFallback | undefined;\n    converter: EnvaptConverter<TFallback> | undefined;\n    hasFallback: boolean;\n    required: boolean;\n    schema: StandardSchemaV1 | undefined;\n}\n\nfunction formatKeyForError(key: EnvKeyInput): string {\n    return Array.isArray(key) ? `[${key.join(', ')}]` : String(key);\n}\n\nconst classIds = new WeakMap<object, number>();\nlet nextClassId = 0;\n\n// keyed on the constructor object, not its name, so two same-named classes (and a same-named\n// static/instance pair) stay in separate cache slots\nexport function decoratorCacheKey(owner: object, isStatic: boolean, prop: string): string {\n    let id = classIds.get(owner);\n    if (id === undefined) {\n        id = nextClassId++;\n        classIds.set(owner, id);\n    }\n    return `${id}.${isStatic ? 'static' : 'instance'}.${prop}`;\n}\n\nexport function resolveDecoratorValue<TFallback>(\n    key: EnvKeyInput,\n    config: DecoratorConfig<TFallback>,\n    cacheKey: string\n): TFallback | null | undefined {\n    const { fallback, converter, hasFallback, required, schema } = config;\n\n    // .has(), not a get()-truthiness check, so a cached undefined (fallback: undefined, or a converter\n    // that returns undefined) resolves once instead of re-running on every access\n    if (EnvaptCache.has(cacheKey)) return EnvaptCache.get(cacheKey) as TFallback | null | undefined;\n\n    const envapter = new Envapter();\n\n    if (required && schema === undefined) {\n        const rawValue = envapter.getRaw(key);\n        if (rawValue === undefined || rawValue.trim() === '') {\n            throw new EnvaptError(\n                EnvaptErrorCodes.MissingEnvValue,\n                `Required environment variable \"${formatKeyForError(key)}\" is missing or empty.`\n            );\n        }\n    }\n\n    const valueConverter = new ValueConverter(envapter);\n    const value =\n        schema !== undefined\n            ? (valueConverter.convertWithSchema(key, schema, fallback, hasFallback) as TFallback)\n            : valueConverter.convertValue(key, fallback, converter, hasFallback);\n\n    EnvaptCache.set(cacheKey, value);\n    return value;\n}\n"],"mappings":"8JAgBA,SAAS,EAAkB,EAA0B,CACjD,OAAO,MAAM,QAAQ,CAAG,EAAI,IAAI,EAAI,KAAK,IAAI,EAAE,GAAK,OAAO,CAAG,CAClE,CAEA,MAAM,EAAW,IAAI,QACrB,IAAI,EAAc,EAIlB,SAAgB,EAAkB,EAAe,EAAmB,EAAsB,CACtF,IAAI,EAAK,EAAS,IAAI,CAAK,EAK3B,OAJI,IAAO,IAAA,KACP,EAAK,IACL,EAAS,IAAI,EAAO,CAAE,GAEnB,GAAG,EAAG,GAAG,EAAW,SAAW,WAAW,GAAG,GACxD,CAEA,SAAgB,EACZ,EACA,EACA,EAC4B,CAC5B,GAAM,CAAE,WAAU,YAAW,cAAa,WAAU,UAAW,EAI/D,GAAIA,EAAAA,YAAY,IAAI,CAAQ,EAAG,OAAOA,EAAAA,YAAY,IAAI,CAAQ,EAE9D,IAAM,EAAW,IAAIC,EAAAA,SAErB,GAAI,GAAY,IAAW,IAAA,GAAW,CAClC,IAAM,EAAW,EAAS,OAAO,CAAG,EACpC,GAAI,IAAa,IAAA,IAAa,EAAS,KAAK,IAAM,GAC9C,MAAM,IAAIC,EAAAA,YAAAA,IAEN,kCAAkC,EAAkB,CAAG,EAAE,uBAC7D,CAER,CAEA,IAAM,EAAiB,IAAIC,EAAAA,eAAe,CAAQ,EAC5C,EACF,IAAW,IAAA,GAEL,EAAe,aAAa,EAAK,EAAU,EAAW,CAAW,EADhE,EAAe,kBAAkB,EAAK,EAAQ,EAAU,CAAW,EAI9E,OADA,EAAA,YAAY,IAAI,EAAU,CAAK,EACxB,CACX"}
+{"version":3,"file":"resolveDecoratorValue.cjs","names":["cache","Envapter","EnvaptError","ValueConverter"],"sources":["../../../src/decorators/resolveDecoratorValue.ts"],"sourcesContent":["import { ValueConverter } from '../converters';\nimport { cache } from '../core/state';\nimport { Envapter } from '../engine/Envapter';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { StandardSchemaV1 } from '../infra/StandardSchema';\nimport type { EnvaptConverter, EnvKeyInput } from '../types';\n\nexport interface DecoratorConfig<TFallback> {\n    fallback: TFallback | undefined;\n    converter: EnvaptConverter<TFallback> | undefined;\n    hasFallback: boolean;\n    required: boolean;\n    schema: StandardSchemaV1 | undefined;\n}\n\nfunction formatKeyForError(key: EnvKeyInput): string {\n    return Array.isArray(key) ? `[${key.join(', ')}]` : String(key);\n}\n\nconst classIds = new WeakMap<object, number>();\nlet nextClassId = 0;\n\n// keyed on the constructor object, not its name, so two same-named classes (and a same-named\n// static/instance pair) stay in separate cache slots\nexport function decoratorCacheKey(owner: object, isStatic: boolean, prop: string): string {\n    let id = classIds.get(owner);\n    if (id === undefined) {\n        id = nextClassId++;\n        classIds.set(owner, id);\n    }\n    return `${id}.${isStatic ? 'static' : 'instance'}.${prop}`;\n}\n\nexport function resolveDecoratorValue<TFallback>(\n    key: EnvKeyInput,\n    config: DecoratorConfig<TFallback>,\n    cacheKey: string\n): TFallback | null | undefined {\n    const { fallback, converter, hasFallback, required, schema } = config;\n\n    // .has(), not a get()-truthiness check, so a cached undefined (fallback: undefined, or a converter\n    // that returns undefined) resolves once instead of re-running on every access\n    if (cache.has(cacheKey)) return cache.get(cacheKey) as TFallback | null | undefined;\n\n    const envapter = new Envapter();\n\n    if (required && schema === undefined) {\n        const rawValue = envapter.getRaw(key);\n        if (rawValue === undefined || rawValue.trim() === '') {\n            throw new EnvaptError(\n                EnvaptErrorCodes.MissingEnvValue,\n                `Required environment variable \"${formatKeyForError(key)}\" is missing or empty.`\n            );\n        }\n    }\n\n    const valueConverter = new ValueConverter(envapter);\n    const value =\n        schema !== undefined\n            ? (valueConverter.convertWithSchema(key, schema, fallback, hasFallback) as TFallback)\n            : valueConverter.convertValue(key, fallback, converter, hasFallback);\n\n    cache.set(cacheKey, value);\n    return value;\n}\n"],"mappings":"uJAgBA,SAAS,EAAkB,EAA0B,CACjD,OAAO,MAAM,QAAQ,CAAG,EAAI,IAAI,EAAI,KAAK,IAAI,EAAE,GAAK,OAAO,CAAG,CAClE,CAEA,MAAM,EAAW,IAAI,QACrB,IAAI,EAAc,EAIlB,SAAgB,EAAkB,EAAe,EAAmB,EAAsB,CACtF,IAAI,EAAK,EAAS,IAAI,CAAK,EAK3B,OAJI,IAAO,IAAA,KACP,EAAK,IACL,EAAS,IAAI,EAAO,CAAE,GAEnB,GAAG,EAAG,GAAG,EAAW,SAAW,WAAW,GAAG,GACxD,CAEA,SAAgB,EACZ,EACA,EACA,EAC4B,CAC5B,GAAM,CAAE,WAAU,YAAW,cAAa,WAAU,UAAW,EAI/D,GAAIA,EAAAA,MAAM,IAAI,CAAQ,EAAG,OAAOA,EAAAA,MAAM,IAAI,CAAQ,EAElD,IAAM,EAAW,IAAIC,EAAAA,SAErB,GAAI,GAAY,IAAW,IAAA,GAAW,CAClC,IAAM,EAAW,EAAS,OAAO,CAAG,EACpC,GAAI,IAAa,IAAA,IAAa,EAAS,KAAK,IAAM,GAC9C,MAAM,IAAIC,EAAAA,YAAAA,IAEN,kCAAkC,EAAkB,CAAG,EAAE,uBAC7D,CAER,CAEA,IAAM,EAAiB,IAAIC,EAAAA,eAAe,CAAQ,EAC5C,EACF,IAAW,IAAA,GAEL,EAAe,aAAa,EAAK,EAAU,EAAW,CAAW,EADhE,EAAe,kBAAkB,EAAK,EAAQ,EAAU,CAAW,EAI9E,OADA,EAAA,MAAM,IAAI,EAAU,CAAK,EAClB,CACX"}

package/dist/node/decorators/resolveDecoratorValue.mjs

@@ -1,2 +1,2 @@
-import{EnvaptError as e}from"../infra/Error.mjs";import{EnvaptCache as t}from"../core/EnvapterBase.mjs";import{ValueConverter as n}from"../converters/ValueConverter.mjs";import{Envapter as r}from"../engine/Envapter.mjs";function i(e){return Array.isArray(e)?`[${e.join(`, `)}]`:String(e)}const a=new WeakMap;let o=0;function s(e,t,n){let r=a.get(e);return r===void 0&&(r=o++,a.set(e,r)),`${r}.${t?`static`:`instance`}.${n}`}function c(a,o,s){let{fallback:c,converter:l,hasFallback:u,required:d,schema:f}=o;if(t.has(s))return t.get(s);let p=new r;if(d&&f===void 0){let t=p.getRaw(a);if(t===void 0||t.trim()===``)throw new e(305,`Required environment variable "${i(a)}" is missing or empty.`)}let m=new n(p),h=f===void 0?m.convertValue(a,c,l,u):m.convertWithSchema(a,f,c,u);return t.set(s,h),h}export{s as decoratorCacheKey,c as resolveDecoratorValue};
+import{EnvaptError as e}from"../infra/Error.mjs";import{cache as t}from"../core/state.mjs";import{ValueConverter as n}from"../converters/ValueConverter.mjs";import{Envapter as r}from"../engine/Envapter.mjs";function i(e){return Array.isArray(e)?`[${e.join(`, `)}]`:String(e)}const a=new WeakMap;let o=0;function s(e,t,n){let r=a.get(e);return r===void 0&&(r=o++,a.set(e,r)),`${r}.${t?`static`:`instance`}.${n}`}function c(a,o,s){let{fallback:c,converter:l,hasFallback:u,required:d,schema:f}=o;if(t.has(s))return t.get(s);let p=new r;if(d&&f===void 0){let t=p.getRaw(a);if(t===void 0||t.trim()===``)throw new e(305,`Required environment variable "${i(a)}" is missing or empty.`)}let m=new n(p),h=f===void 0?m.convertValue(a,c,l,u):m.convertWithSchema(a,f,c,u);return t.set(s,h),h}export{s as decoratorCacheKey,c as resolveDecoratorValue};
 //# sourceMappingURL=resolveDecoratorValue.mjs.map

package/dist/node/decorators/resolveDecoratorValue.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"resolveDecoratorValue.mjs","names":[],"sources":["../../../src/decorators/resolveDecoratorValue.ts"],"sourcesContent":["import { ValueConverter } from '../converters';\nimport { EnvaptCache } from '../core';\nimport { Envapter } from '../engine/Envapter';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { StandardSchemaV1 } from '../infra/StandardSchema';\nimport type { EnvaptConverter, EnvKeyInput } from '../types';\n\nexport interface DecoratorConfig<TFallback> {\n    fallback: TFallback | undefined;\n    converter: EnvaptConverter<TFallback> | undefined;\n    hasFallback: boolean;\n    required: boolean;\n    schema: StandardSchemaV1 | undefined;\n}\n\nfunction formatKeyForError(key: EnvKeyInput): string {\n    return Array.isArray(key) ? `[${key.join(', ')}]` : String(key);\n}\n\nconst classIds = new WeakMap<object, number>();\nlet nextClassId = 0;\n\n// keyed on the constructor object, not its name, so two same-named classes (and a same-named\n// static/instance pair) stay in separate cache slots\nexport function decoratorCacheKey(owner: object, isStatic: boolean, prop: string): string {\n    let id = classIds.get(owner);\n    if (id === undefined) {\n        id = nextClassId++;\n        classIds.set(owner, id);\n    }\n    return `${id}.${isStatic ? 'static' : 'instance'}.${prop}`;\n}\n\nexport function resolveDecoratorValue<TFallback>(\n    key: EnvKeyInput,\n    config: DecoratorConfig<TFallback>,\n    cacheKey: string\n): TFallback | null | undefined {\n    const { fallback, converter, hasFallback, required, schema } = config;\n\n    // .has(), not a get()-truthiness check, so a cached undefined (fallback: undefined, or a converter\n    // that returns undefined) resolves once instead of re-running on every access\n    if (EnvaptCache.has(cacheKey)) return EnvaptCache.get(cacheKey) as TFallback | null | undefined;\n\n    const envapter = new Envapter();\n\n    if (required && schema === undefined) {\n        const rawValue = envapter.getRaw(key);\n        if (rawValue === undefined || rawValue.trim() === '') {\n            throw new EnvaptError(\n                EnvaptErrorCodes.MissingEnvValue,\n                `Required environment variable \"${formatKeyForError(key)}\" is missing or empty.`\n            );\n        }\n    }\n\n    const valueConverter = new ValueConverter(envapter);\n    const value =\n        schema !== undefined\n            ? (valueConverter.convertWithSchema(key, schema, fallback, hasFallback) as TFallback)\n            : valueConverter.convertValue(key, fallback, converter, hasFallback);\n\n    EnvaptCache.set(cacheKey, value);\n    return value;\n}\n"],"mappings":"4NAgBA,SAAS,EAAkB,EAA0B,CACjD,OAAO,MAAM,QAAQ,CAAG,EAAI,IAAI,EAAI,KAAK,IAAI,EAAE,GAAK,OAAO,CAAG,CAClE,CAEA,MAAM,EAAW,IAAI,QACrB,IAAI,EAAc,EAIlB,SAAgB,EAAkB,EAAe,EAAmB,EAAsB,CACtF,IAAI,EAAK,EAAS,IAAI,CAAK,EAK3B,OAJI,IAAO,IAAA,KACP,EAAK,IACL,EAAS,IAAI,EAAO,CAAE,GAEnB,GAAG,EAAG,GAAG,EAAW,SAAW,WAAW,GAAG,GACxD,CAEA,SAAgB,EACZ,EACA,EACA,EAC4B,CAC5B,GAAM,CAAE,WAAU,YAAW,cAAa,WAAU,UAAW,EAI/D,GAAI,EAAY,IAAI,CAAQ,EAAG,OAAO,EAAY,IAAI,CAAQ,EAE9D,IAAM,EAAW,IAAI,EAErB,GAAI,GAAY,IAAW,IAAA,GAAW,CAClC,IAAM,EAAW,EAAS,OAAO,CAAG,EACpC,GAAI,IAAa,IAAA,IAAa,EAAS,KAAK,IAAM,GAC9C,MAAM,IAAI,EAAA,IAEN,kCAAkC,EAAkB,CAAG,EAAE,uBAC7D,CAER,CAEA,IAAM,EAAiB,IAAI,EAAe,CAAQ,EAC5C,EACF,IAAW,IAAA,GAEL,EAAe,aAAa,EAAK,EAAU,EAAW,CAAW,EADhE,EAAe,kBAAkB,EAAK,EAAQ,EAAU,CAAW,EAI9E,OADA,EAAY,IAAI,EAAU,CAAK,EACxB,CACX"}
+{"version":3,"file":"resolveDecoratorValue.mjs","names":[],"sources":["../../../src/decorators/resolveDecoratorValue.ts"],"sourcesContent":["import { ValueConverter } from '../converters';\nimport { cache } from '../core/state';\nimport { Envapter } from '../engine/Envapter';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { StandardSchemaV1 } from '../infra/StandardSchema';\nimport type { EnvaptConverter, EnvKeyInput } from '../types';\n\nexport interface DecoratorConfig<TFallback> {\n    fallback: TFallback | undefined;\n    converter: EnvaptConverter<TFallback> | undefined;\n    hasFallback: boolean;\n    required: boolean;\n    schema: StandardSchemaV1 | undefined;\n}\n\nfunction formatKeyForError(key: EnvKeyInput): string {\n    return Array.isArray(key) ? `[${key.join(', ')}]` : String(key);\n}\n\nconst classIds = new WeakMap<object, number>();\nlet nextClassId = 0;\n\n// keyed on the constructor object, not its name, so two same-named classes (and a same-named\n// static/instance pair) stay in separate cache slots\nexport function decoratorCacheKey(owner: object, isStatic: boolean, prop: string): string {\n    let id = classIds.get(owner);\n    if (id === undefined) {\n        id = nextClassId++;\n        classIds.set(owner, id);\n    }\n    return `${id}.${isStatic ? 'static' : 'instance'}.${prop}`;\n}\n\nexport function resolveDecoratorValue<TFallback>(\n    key: EnvKeyInput,\n    config: DecoratorConfig<TFallback>,\n    cacheKey: string\n): TFallback | null | undefined {\n    const { fallback, converter, hasFallback, required, schema } = config;\n\n    // .has(), not a get()-truthiness check, so a cached undefined (fallback: undefined, or a converter\n    // that returns undefined) resolves once instead of re-running on every access\n    if (cache.has(cacheKey)) return cache.get(cacheKey) as TFallback | null | undefined;\n\n    const envapter = new Envapter();\n\n    if (required && schema === undefined) {\n        const rawValue = envapter.getRaw(key);\n        if (rawValue === undefined || rawValue.trim() === '') {\n            throw new EnvaptError(\n                EnvaptErrorCodes.MissingEnvValue,\n                `Required environment variable \"${formatKeyForError(key)}\" is missing or empty.`\n            );\n        }\n    }\n\n    const valueConverter = new ValueConverter(envapter);\n    const value =\n        schema !== undefined\n            ? (valueConverter.convertWithSchema(key, schema, fallback, hasFallback) as TFallback)\n            : valueConverter.convertValue(key, fallback, converter, hasFallback);\n\n    cache.set(cacheKey, value);\n    return value;\n}\n"],"mappings":"+MAgBA,SAAS,EAAkB,EAA0B,CACjD,OAAO,MAAM,QAAQ,CAAG,EAAI,IAAI,EAAI,KAAK,IAAI,EAAE,GAAK,OAAO,CAAG,CAClE,CAEA,MAAM,EAAW,IAAI,QACrB,IAAI,EAAc,EAIlB,SAAgB,EAAkB,EAAe,EAAmB,EAAsB,CACtF,IAAI,EAAK,EAAS,IAAI,CAAK,EAK3B,OAJI,IAAO,IAAA,KACP,EAAK,IACL,EAAS,IAAI,EAAO,CAAE,GAEnB,GAAG,EAAG,GAAG,EAAW,SAAW,WAAW,GAAG,GACxD,CAEA,SAAgB,EACZ,EACA,EACA,EAC4B,CAC5B,GAAM,CAAE,WAAU,YAAW,cAAa,WAAU,UAAW,EAI/D,GAAI,EAAM,IAAI,CAAQ,EAAG,OAAO,EAAM,IAAI,CAAQ,EAElD,IAAM,EAAW,IAAI,EAErB,GAAI,GAAY,IAAW,IAAA,GAAW,CAClC,IAAM,EAAW,EAAS,OAAO,CAAG,EACpC,GAAI,IAAa,IAAA,IAAa,EAAS,KAAK,IAAM,GAC9C,MAAM,IAAI,EAAA,IAEN,kCAAkC,EAAkB,CAAG,EAAE,uBAC7D,CAER,CAEA,IAAM,EAAiB,IAAI,EAAe,CAAQ,EAC5C,EACF,IAAW,IAAA,GAEL,EAAe,aAAa,EAAK,EAAU,EAAW,CAAW,EADhE,EAAe,kBAAkB,EAAK,EAAQ,EAAU,CAAW,EAI9E,OADA,EAAM,IAAI,EAAU,CAAK,EAClB,CACX"}

package/dist/node/engine/Envapter.cjs

@@ -1,2 +1,2 @@
-const e=require("../infra/Error.cjs");require("../core/EnvapterBase.cjs"),require("../core/EnvironmentMethods.cjs");const t=require("../core/AdvancedMethods.cjs");var n=class n extends t.AdvancedMethods{static resolve(t,...r){let i=n.strict;return t.reduce((t,n,a)=>{let o=r[a];if(!o)return t+n;let s=super.get(o,``);if(i&&s.trim()===``)throw new e.EnvaptError(305,`Cannot resolve template variable "\${${o}}": value is missing or empty.`);return t+n+s},``)}resolve(e,...t){return n.resolve(e,...t)}static require(...t){let r=[];for(let e of t)n.resolveAndValidate(e)===void 0&&r.push(e);if(r.length>0)throw new e.EnvaptError(305,`Missing required environment variables: ${r.join(`, `)}.`)}static resolveAndValidate(e){let{value:t}=this.resolveKeyInput(e);if(t===void 0)return;let n=this.templateResolver.resolveTemplate(e,t);if(n.trim()!==``)return n}require(...e){n.require(...e)}};exports.Envapter=n;
+require("../core/Environment.cjs");const e=require("../infra/Error.cjs"),t=require("../core/engine.cjs"),n=require("../core/AdvancedMethods.cjs");var r=class r extends n.AdvancedMethods{static resolve(t,...n){let i=r.strict;return t.reduce((t,r,a)=>{let o=n[a];if(!o)return t+r;let s=super.get(o,``);if(i&&s.trim()===``)throw new e.EnvaptError(305,`Cannot resolve template variable "\${${o}}": value is missing or empty.`);return t+r+s},``)}resolve(e,...t){return r.resolve(e,...t)}static require(...r){let i=r.filter(e=>n.resolveRequired(t.resolveKeyInput(e),t.templateResolver).value===void 0);if(i.length>0)throw new e.EnvaptError(305,`Missing required environment variables: ${i.join(`, `)}.`)}require(...e){r.require(...e)}};exports.Envapter=r;
 //# sourceMappingURL=Envapter.cjs.map

package/dist/node/engine/Envapter.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"Envapter.cjs","names":["AdvancedMethods","EnvaptError"],"sources":["../../../src/engine/Envapter.ts"],"sourcesContent":["import { AdvancedMethods } from '../core';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nexport { EnvaptCache, Environment } from '../core';\n\n/**\n * Main configuration class for environment variable management.\n *\n * Provides both static and instance methods for retrieving typed environment variables\n * with support for template resolution, multiple .env files, and environment detection.\n *\n * Extend your own classes from this to define properties with \\@Envapt decorators and get access to environment-variable methods.\n *\n * @example\n * ```ts\n * // Static usage\n * const port = Envapter.getNumber('PORT', 3000);\n * const url = Envapter.get('API_URL', 'http://localhost');\n * const replica = Envapter.get(['READONLY_URL', 'DATABASE_URL'], 'sqlite://memory');\n *\n * // Instance usage\n * const env = new Envapter();\n * const dbUrl = env.get('DATABASE_URL', 'sqlite://memory');\n * const primaryHost = env.get(['PRIMARY_HOST', 'SECONDARY_HOST']);\n * ```\n *\n * @public\n */\nexport class Envapter extends AdvancedMethods {\n    /**\n     * Tagged template literal for resolving environment variables in template strings.\n     *\n     * @example\n     * ```ts\n     * // Given API_HOST=api.example.com and API_PORT=8080 in environment\n     * const endpoint = Envapter.resolve`Connecting to ${'API_HOST'}:${'API_PORT'}`;\n     * // Returns: \"Connecting to api.example.com:8080\"\n     *\n     * // Works with template variables in .env too:\n     * // API_URL=https://${API_HOST}:${API_PORT}\n     * const message = Envapter.resolve`Service endpoint: ${'API_URL'}`;\n     * // Returns: \"Service endpoint: https://api.example.com:8080\"\n     * ```\n     */\n    static resolve(strings: TemplateStringsArray, ...keys: string[]): string {\n        const strict = Envapter.strict;\n        return strings.reduce((result, string, i) => {\n            const envKey = keys[i];\n            if (!envKey) return result + string;\n            const raw = super.get(envKey, '');\n            if (strict && raw.trim() === '') {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.MissingEnvValue,\n                    `Cannot resolve template variable \"\\${${envKey}}\": value is missing or empty.`\n                );\n            }\n            return result + string + raw;\n        }, '');\n    }\n\n    /**\n     * @see {@link Envapter.resolve}\n     */\n    resolve(strings: TemplateStringsArray, ...keys: string[]): string {\n        return Envapter.resolve(strings, ...keys);\n    }\n\n    /**\n     * Assert that one or more environment variables are present and non-empty (post-trim,\n     * after template resolution). Throws `MissingEnvValue` listing every missing key.\n     *\n     * For typed fail-fast in functional code, use `Envapter.getUsing(key, { converter, required: true })`.\n     *\n     * @example\n     * ```ts\n     * Envapter.require('DATABASE_URL');\n     * Envapter.require('DATABASE_URL', 'API_KEY', 'SENTRY_DSN');\n     * ```\n     */\n    static require(...keys: [string, ...string[]]): void {\n        const missing: string[] = [];\n        for (const k of keys) {\n            if (Envapter.resolveAndValidate(k) === undefined) missing.push(k);\n        }\n\n        if (missing.length > 0) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.MissingEnvValue,\n                `Missing required environment variables: ${missing.join(', ')}.`\n            );\n        }\n    }\n\n    private static resolveAndValidate(key: string): string | undefined {\n        const { value } = this.resolveKeyInput(key);\n        if (value === undefined) return undefined;\n        const resolved = this.templateResolver.resolveTemplate(key, value);\n        if (resolved.trim() === '') return undefined;\n        return resolved;\n    }\n\n    /**\n     * @see {@link Envapter.require}\n     */\n    require(...keys: [string, ...string[]]): void {\n        Envapter.require(...keys);\n    }\n}\n"],"mappings":"mKA4BA,IAAa,EAAb,MAAa,UAAiBA,EAAAA,eAAgB,CAgB1C,OAAO,QAAQ,EAA+B,GAAG,EAAwB,CACrE,IAAM,EAAS,EAAS,OACxB,OAAO,EAAQ,QAAQ,EAAQ,EAAQ,IAAM,CACzC,IAAM,EAAS,EAAK,GACpB,GAAI,CAAC,EAAQ,OAAO,EAAS,EAC7B,IAAM,EAAM,MAAM,IAAI,EAAQ,EAAE,EAChC,GAAI,GAAU,EAAI,KAAK,IAAM,GACzB,MAAM,IAAIC,EAAAA,YAAAA,IAEN,wCAAwC,EAAO,+BACnD,EAEJ,OAAO,EAAS,EAAS,CAC7B,EAAG,EAAE,CACT,CAKA,QAAQ,EAA+B,GAAG,EAAwB,CAC9D,OAAO,EAAS,QAAQ,EAAS,GAAG,CAAI,CAC5C,CAcA,OAAO,QAAQ,GAAG,EAAmC,CACjD,IAAM,EAAoB,CAAC,EAC3B,IAAK,IAAM,KAAK,EACR,EAAS,mBAAmB,CAAC,IAAM,IAAA,IAAW,EAAQ,KAAK,CAAC,EAGpE,GAAI,EAAQ,OAAS,EACjB,MAAM,IAAIA,EAAAA,YAAAA,IAEN,2CAA2C,EAAQ,KAAK,IAAI,EAAE,EAClE,CAER,CAEA,OAAe,mBAAmB,EAAiC,CAC/D,GAAM,CAAE,SAAU,KAAK,gBAAgB,CAAG,EAC1C,GAAI,IAAU,IAAA,GAAW,OACzB,IAAM,EAAW,KAAK,iBAAiB,gBAAgB,EAAK,CAAK,EAC7D,KAAS,KAAK,IAAM,GACxB,OAAO,CACX,CAKA,QAAQ,GAAG,EAAmC,CAC1C,EAAS,QAAQ,GAAG,CAAI,CAC5B,CACJ"}
+{"version":3,"file":"Envapter.cjs","names":["AdvancedMethods","EnvaptError","resolveRequired","resolveKeyInput","templateResolver"],"sources":["../../../src/engine/Envapter.ts"],"sourcesContent":["import { AdvancedMethods } from '../core';\nimport { resolveRequired } from '../core/AdvancedMethods';\nimport { resolveKeyInput, templateResolver } from '../core/engine';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nexport { Environment } from '../core';\n\n/**\n * Main configuration class for environment variable management.\n *\n * Provides both static and instance methods for retrieving typed environment variables\n * with support for template resolution, multiple .env files, and environment detection.\n *\n * Extend your own classes from this to define properties with \\@Envapt decorators and get access to environment-variable methods.\n *\n * @example\n * ```ts\n * // Static usage\n * const port = Envapter.getNumber('PORT', 3000);\n * const url = Envapter.get('API_URL', 'http://localhost');\n * const replica = Envapter.get(['READONLY_URL', 'DATABASE_URL'], 'sqlite://memory');\n *\n * // Instance usage\n * const env = new Envapter();\n * const dbUrl = env.get('DATABASE_URL', 'sqlite://memory');\n * const primaryHost = env.get(['PRIMARY_HOST', 'SECONDARY_HOST']);\n * ```\n *\n * @public\n */\nexport class Envapter extends AdvancedMethods {\n    /**\n     * Tagged template literal for resolving environment variables in template strings.\n     *\n     * @example\n     * ```ts\n     * // Given API_HOST=api.example.com and API_PORT=8080 in environment\n     * const endpoint = Envapter.resolve`Connecting to ${'API_HOST'}:${'API_PORT'}`;\n     * // Returns: \"Connecting to api.example.com:8080\"\n     *\n     * // Works with template variables in .env too:\n     * // API_URL=https://${API_HOST}:${API_PORT}\n     * const message = Envapter.resolve`Service endpoint: ${'API_URL'}`;\n     * // Returns: \"Service endpoint: https://api.example.com:8080\"\n     * ```\n     */\n    static resolve(strings: TemplateStringsArray, ...keys: string[]): string {\n        const strict = Envapter.strict;\n        return strings.reduce((result, string, i) => {\n            const envKey = keys[i];\n            if (!envKey) return result + string;\n            const raw = super.get(envKey, '');\n            if (strict && raw.trim() === '') {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.MissingEnvValue,\n                    `Cannot resolve template variable \"\\${${envKey}}\": value is missing or empty.`\n                );\n            }\n            return result + string + raw;\n        }, '');\n    }\n\n    /**\n     * @see {@link Envapter.resolve}\n     */\n    resolve(strings: TemplateStringsArray, ...keys: string[]): string {\n        return Envapter.resolve(strings, ...keys);\n    }\n\n    /**\n     * Assert that one or more environment variables are present and non-empty (post-trim,\n     * after template resolution). Throws `MissingEnvValue` listing every missing key.\n     *\n     * For a typed required read in functional code, use `Envapter.getRequired(key, converter)`.\n     *\n     * @example\n     * ```ts\n     * Envapter.require('DATABASE_URL');\n     * Envapter.require('DATABASE_URL', 'API_KEY', 'SENTRY_DSN');\n     * ```\n     */\n    static require(...keys: [string, ...string[]]): void {\n        const missing = keys.filter((k) => resolveRequired(resolveKeyInput(k), templateResolver).value === undefined);\n\n        if (missing.length > 0) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.MissingEnvValue,\n                `Missing required environment variables: ${missing.join(', ')}.`\n            );\n        }\n    }\n\n    /**\n     * @see {@link Envapter.require}\n     */\n    require(...keys: [string, ...string[]]): void {\n        Envapter.require(...keys);\n    }\n}\n"],"mappings":"kJA8BA,IAAa,EAAb,MAAa,UAAiBA,EAAAA,eAAgB,CAgB1C,OAAO,QAAQ,EAA+B,GAAG,EAAwB,CACrE,IAAM,EAAS,EAAS,OACxB,OAAO,EAAQ,QAAQ,EAAQ,EAAQ,IAAM,CACzC,IAAM,EAAS,EAAK,GACpB,GAAI,CAAC,EAAQ,OAAO,EAAS,EAC7B,IAAM,EAAM,MAAM,IAAI,EAAQ,EAAE,EAChC,GAAI,GAAU,EAAI,KAAK,IAAM,GACzB,MAAM,IAAIC,EAAAA,YAAAA,IAEN,wCAAwC,EAAO,+BACnD,EAEJ,OAAO,EAAS,EAAS,CAC7B,EAAG,EAAE,CACT,CAKA,QAAQ,EAA+B,GAAG,EAAwB,CAC9D,OAAO,EAAS,QAAQ,EAAS,GAAG,CAAI,CAC5C,CAcA,OAAO,QAAQ,GAAG,EAAmC,CACjD,IAAM,EAAU,EAAK,OAAQ,GAAMC,EAAAA,gBAAgBC,EAAAA,gBAAgB,CAAC,EAAGC,EAAAA,gBAAgB,CAAC,CAAC,QAAU,IAAA,EAAS,EAE5G,GAAI,EAAQ,OAAS,EACjB,MAAM,IAAIH,EAAAA,YAAAA,IAEN,2CAA2C,EAAQ,KAAK,IAAI,EAAE,EAClE,CAER,CAKA,QAAQ,GAAG,EAAmC,CAC1C,EAAS,QAAQ,GAAG,CAAI,CAC5B,CACJ"}

package/dist/node/engine/Envapter.mjs

@@ -1,2 +1,2 @@
-import{EnvaptError as e}from"../infra/Error.mjs";import"../core/EnvapterBase.mjs";import"../core/EnvironmentMethods.mjs";import{AdvancedMethods as t}from"../core/AdvancedMethods.mjs";var n=class n extends t{static resolve(t,...r){let i=n.strict;return t.reduce((t,n,a)=>{let o=r[a];if(!o)return t+n;let s=super.get(o,``);if(i&&s.trim()===``)throw new e(305,`Cannot resolve template variable "\${${o}}": value is missing or empty.`);return t+n+s},``)}resolve(e,...t){return n.resolve(e,...t)}static require(...t){let r=[];for(let e of t)n.resolveAndValidate(e)===void 0&&r.push(e);if(r.length>0)throw new e(305,`Missing required environment variables: ${r.join(`, `)}.`)}static resolveAndValidate(e){let{value:t}=this.resolveKeyInput(e);if(t===void 0)return;let n=this.templateResolver.resolveTemplate(e,t);if(n.trim()!==``)return n}require(...e){n.require(...e)}};export{n as Envapter};
+import"../core/Environment.mjs";import{EnvaptError as e}from"../infra/Error.mjs";import{resolveKeyInput as t,templateResolver as n}from"../core/engine.mjs";import{AdvancedMethods as r,resolveRequired as i}from"../core/AdvancedMethods.mjs";var a=class a extends r{static resolve(t,...n){let r=a.strict;return t.reduce((t,i,a)=>{let o=n[a];if(!o)return t+i;let s=super.get(o,``);if(r&&s.trim()===``)throw new e(305,`Cannot resolve template variable "\${${o}}": value is missing or empty.`);return t+i+s},``)}resolve(e,...t){return a.resolve(e,...t)}static require(...r){let a=r.filter(e=>i(t(e),n).value===void 0);if(a.length>0)throw new e(305,`Missing required environment variables: ${a.join(`, `)}.`)}require(...e){a.require(...e)}};export{a as Envapter};
 //# sourceMappingURL=Envapter.mjs.map

package/dist/node/engine/Envapter.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"Envapter.mjs","names":[],"sources":["../../../src/engine/Envapter.ts"],"sourcesContent":["import { AdvancedMethods } from '../core';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nexport { EnvaptCache, Environment } from '../core';\n\n/**\n * Main configuration class for environment variable management.\n *\n * Provides both static and instance methods for retrieving typed environment variables\n * with support for template resolution, multiple .env files, and environment detection.\n *\n * Extend your own classes from this to define properties with \\@Envapt decorators and get access to environment-variable methods.\n *\n * @example\n * ```ts\n * // Static usage\n * const port = Envapter.getNumber('PORT', 3000);\n * const url = Envapter.get('API_URL', 'http://localhost');\n * const replica = Envapter.get(['READONLY_URL', 'DATABASE_URL'], 'sqlite://memory');\n *\n * // Instance usage\n * const env = new Envapter();\n * const dbUrl = env.get('DATABASE_URL', 'sqlite://memory');\n * const primaryHost = env.get(['PRIMARY_HOST', 'SECONDARY_HOST']);\n * ```\n *\n * @public\n */\nexport class Envapter extends AdvancedMethods {\n    /**\n     * Tagged template literal for resolving environment variables in template strings.\n     *\n     * @example\n     * ```ts\n     * // Given API_HOST=api.example.com and API_PORT=8080 in environment\n     * const endpoint = Envapter.resolve`Connecting to ${'API_HOST'}:${'API_PORT'}`;\n     * // Returns: \"Connecting to api.example.com:8080\"\n     *\n     * // Works with template variables in .env too:\n     * // API_URL=https://${API_HOST}:${API_PORT}\n     * const message = Envapter.resolve`Service endpoint: ${'API_URL'}`;\n     * // Returns: \"Service endpoint: https://api.example.com:8080\"\n     * ```\n     */\n    static resolve(strings: TemplateStringsArray, ...keys: string[]): string {\n        const strict = Envapter.strict;\n        return strings.reduce((result, string, i) => {\n            const envKey = keys[i];\n            if (!envKey) return result + string;\n            const raw = super.get(envKey, '');\n            if (strict && raw.trim() === '') {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.MissingEnvValue,\n                    `Cannot resolve template variable \"\\${${envKey}}\": value is missing or empty.`\n                );\n            }\n            return result + string + raw;\n        }, '');\n    }\n\n    /**\n     * @see {@link Envapter.resolve}\n     */\n    resolve(strings: TemplateStringsArray, ...keys: string[]): string {\n        return Envapter.resolve(strings, ...keys);\n    }\n\n    /**\n     * Assert that one or more environment variables are present and non-empty (post-trim,\n     * after template resolution). Throws `MissingEnvValue` listing every missing key.\n     *\n     * For typed fail-fast in functional code, use `Envapter.getUsing(key, { converter, required: true })`.\n     *\n     * @example\n     * ```ts\n     * Envapter.require('DATABASE_URL');\n     * Envapter.require('DATABASE_URL', 'API_KEY', 'SENTRY_DSN');\n     * ```\n     */\n    static require(...keys: [string, ...string[]]): void {\n        const missing: string[] = [];\n        for (const k of keys) {\n            if (Envapter.resolveAndValidate(k) === undefined) missing.push(k);\n        }\n\n        if (missing.length > 0) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.MissingEnvValue,\n                `Missing required environment variables: ${missing.join(', ')}.`\n            );\n        }\n    }\n\n    private static resolveAndValidate(key: string): string | undefined {\n        const { value } = this.resolveKeyInput(key);\n        if (value === undefined) return undefined;\n        const resolved = this.templateResolver.resolveTemplate(key, value);\n        if (resolved.trim() === '') return undefined;\n        return resolved;\n    }\n\n    /**\n     * @see {@link Envapter.require}\n     */\n    require(...keys: [string, ...string[]]): void {\n        Envapter.require(...keys);\n    }\n}\n"],"mappings":"uLA4BA,IAAa,EAAb,MAAa,UAAiB,CAAgB,CAgB1C,OAAO,QAAQ,EAA+B,GAAG,EAAwB,CACrE,IAAM,EAAS,EAAS,OACxB,OAAO,EAAQ,QAAQ,EAAQ,EAAQ,IAAM,CACzC,IAAM,EAAS,EAAK,GACpB,GAAI,CAAC,EAAQ,OAAO,EAAS,EAC7B,IAAM,EAAM,MAAM,IAAI,EAAQ,EAAE,EAChC,GAAI,GAAU,EAAI,KAAK,IAAM,GACzB,MAAM,IAAI,EAAA,IAEN,wCAAwC,EAAO,+BACnD,EAEJ,OAAO,EAAS,EAAS,CAC7B,EAAG,EAAE,CACT,CAKA,QAAQ,EAA+B,GAAG,EAAwB,CAC9D,OAAO,EAAS,QAAQ,EAAS,GAAG,CAAI,CAC5C,CAcA,OAAO,QAAQ,GAAG,EAAmC,CACjD,IAAM,EAAoB,CAAC,EAC3B,IAAK,IAAM,KAAK,EACR,EAAS,mBAAmB,CAAC,IAAM,IAAA,IAAW,EAAQ,KAAK,CAAC,EAGpE,GAAI,EAAQ,OAAS,EACjB,MAAM,IAAI,EAAA,IAEN,2CAA2C,EAAQ,KAAK,IAAI,EAAE,EAClE,CAER,CAEA,OAAe,mBAAmB,EAAiC,CAC/D,GAAM,CAAE,SAAU,KAAK,gBAAgB,CAAG,EAC1C,GAAI,IAAU,IAAA,GAAW,OACzB,IAAM,EAAW,KAAK,iBAAiB,gBAAgB,EAAK,CAAK,EAC7D,KAAS,KAAK,IAAM,GACxB,OAAO,CACX,CAKA,QAAQ,GAAG,EAAmC,CAC1C,EAAS,QAAQ,GAAG,CAAI,CAC5B,CACJ"}
+{"version":3,"file":"Envapter.mjs","names":[],"sources":["../../../src/engine/Envapter.ts"],"sourcesContent":["import { AdvancedMethods } from '../core';\nimport { resolveRequired } from '../core/AdvancedMethods';\nimport { resolveKeyInput, templateResolver } from '../core/engine';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nexport { Environment } from '../core';\n\n/**\n * Main configuration class for environment variable management.\n *\n * Provides both static and instance methods for retrieving typed environment variables\n * with support for template resolution, multiple .env files, and environment detection.\n *\n * Extend your own classes from this to define properties with \\@Envapt decorators and get access to environment-variable methods.\n *\n * @example\n * ```ts\n * // Static usage\n * const port = Envapter.getNumber('PORT', 3000);\n * const url = Envapter.get('API_URL', 'http://localhost');\n * const replica = Envapter.get(['READONLY_URL', 'DATABASE_URL'], 'sqlite://memory');\n *\n * // Instance usage\n * const env = new Envapter();\n * const dbUrl = env.get('DATABASE_URL', 'sqlite://memory');\n * const primaryHost = env.get(['PRIMARY_HOST', 'SECONDARY_HOST']);\n * ```\n *\n * @public\n */\nexport class Envapter extends AdvancedMethods {\n    /**\n     * Tagged template literal for resolving environment variables in template strings.\n     *\n     * @example\n     * ```ts\n     * // Given API_HOST=api.example.com and API_PORT=8080 in environment\n     * const endpoint = Envapter.resolve`Connecting to ${'API_HOST'}:${'API_PORT'}`;\n     * // Returns: \"Connecting to api.example.com:8080\"\n     *\n     * // Works with template variables in .env too:\n     * // API_URL=https://${API_HOST}:${API_PORT}\n     * const message = Envapter.resolve`Service endpoint: ${'API_URL'}`;\n     * // Returns: \"Service endpoint: https://api.example.com:8080\"\n     * ```\n     */\n    static resolve(strings: TemplateStringsArray, ...keys: string[]): string {\n        const strict = Envapter.strict;\n        return strings.reduce((result, string, i) => {\n            const envKey = keys[i];\n            if (!envKey) return result + string;\n            const raw = super.get(envKey, '');\n            if (strict && raw.trim() === '') {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.MissingEnvValue,\n                    `Cannot resolve template variable \"\\${${envKey}}\": value is missing or empty.`\n                );\n            }\n            return result + string + raw;\n        }, '');\n    }\n\n    /**\n     * @see {@link Envapter.resolve}\n     */\n    resolve(strings: TemplateStringsArray, ...keys: string[]): string {\n        return Envapter.resolve(strings, ...keys);\n    }\n\n    /**\n     * Assert that one or more environment variables are present and non-empty (post-trim,\n     * after template resolution). Throws `MissingEnvValue` listing every missing key.\n     *\n     * For a typed required read in functional code, use `Envapter.getRequired(key, converter)`.\n     *\n     * @example\n     * ```ts\n     * Envapter.require('DATABASE_URL');\n     * Envapter.require('DATABASE_URL', 'API_KEY', 'SENTRY_DSN');\n     * ```\n     */\n    static require(...keys: [string, ...string[]]): void {\n        const missing = keys.filter((k) => resolveRequired(resolveKeyInput(k), templateResolver).value === undefined);\n\n        if (missing.length > 0) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.MissingEnvValue,\n                `Missing required environment variables: ${missing.join(', ')}.`\n            );\n        }\n    }\n\n    /**\n     * @see {@link Envapter.require}\n     */\n    require(...keys: [string, ...string[]]): void {\n        Envapter.require(...keys);\n    }\n}\n"],"mappings":"+OA8BA,IAAa,EAAb,MAAa,UAAiB,CAAgB,CAgB1C,OAAO,QAAQ,EAA+B,GAAG,EAAwB,CACrE,IAAM,EAAS,EAAS,OACxB,OAAO,EAAQ,QAAQ,EAAQ,EAAQ,IAAM,CACzC,IAAM,EAAS,EAAK,GACpB,GAAI,CAAC,EAAQ,OAAO,EAAS,EAC7B,IAAM,EAAM,MAAM,IAAI,EAAQ,EAAE,EAChC,GAAI,GAAU,EAAI,KAAK,IAAM,GACzB,MAAM,IAAI,EAAA,IAEN,wCAAwC,EAAO,+BACnD,EAEJ,OAAO,EAAS,EAAS,CAC7B,EAAG,EAAE,CACT,CAKA,QAAQ,EAA+B,GAAG,EAAwB,CAC9D,OAAO,EAAS,QAAQ,EAAS,GAAG,CAAI,CAC5C,CAcA,OAAO,QAAQ,GAAG,EAAmC,CACjD,IAAM,EAAU,EAAK,OAAQ,GAAM,EAAgB,EAAgB,CAAC,EAAG,CAAgB,CAAC,CAAC,QAAU,IAAA,EAAS,EAE5G,GAAI,EAAQ,OAAS,EACjB,MAAM,IAAI,EAAA,IAEN,2CAA2C,EAAQ,KAAK,IAAI,EAAE,EAClE,CAER,CAKA,QAAQ,GAAG,EAAmC,CAC1C,EAAS,QAAQ,GAAG,CAAI,CAC5B,CACJ"}

package/dist/node/engine/NodeEnvapter.cjs

@@ -1,2 +1,2 @@
-const e=require("../_virtual/_rolldown/runtime.cjs"),t=require("./Validators.cjs"),n=require("../infra/runtime.cjs"),r=require("../core/EnvapterBase.cjs"),i=require("../core/EnvironmentMethods.cjs"),a=require("./Envapter.cjs"),o=require("../sources/NodeEnvSource.cjs");let s=require("node:process");s=e.__toESM(s,1);var c=class e extends a.Envapter{static{n.setRuntimeSink(e=>s.default.stderr.write(`${e}\n`)),e.useSource(new o.NodeEnvSource)}static set envPaths(e){this.assertFileApiSupported(`envPaths`,r.EnvapterBase._source);let n=Array.isArray(e)?e:[e];t.Validator.validateEnvFilesExist(n.map(e=>this.resolveAgainstBase(e)),e=>this.sourceFileExists(e)),r.EnvapterBase._envPaths=n,r.EnvapterBase._envPathsExplicitlySet=!0,this.refreshCache()}static get envPaths(){return r.EnvapterBase._envPaths}static set baseDir(e){let t=r.EnvapterBase._source;this.assertFileApiSupported(`baseDir`,t),r.EnvapterBase._baseDir=e===void 0?void 0:t.normalizeBaseDir(e),this.refreshCache()}static get baseDir(){return r.EnvapterBase._baseDir}static set envFileOptions(e){t.Validator.validateEnvFileOptions(e),r.EnvapterBase._userDefinedEnvFileOptions=e,this.refreshCache()}static get envFileOptions(){return r.EnvapterBase._userDefinedEnvFileOptions}static configureProfiles(e){this.assertFileApiSupported(`configureProfiles`,r.EnvapterBase._source),i.EnvironmentMethods._profiles=e,this.refreshCache()}static resetProfiles(){i.EnvironmentMethods._profiles=void 0,r.EnvapterBase._envPaths=[`.env`],r.EnvapterBase._envPathsExplicitlySet=!1,this._environmentExplicitlySet=!1,this._environment=void 0,this.refreshCache()}};exports.NodeEnvapter=c;
+const e=require("../_virtual/_rolldown/runtime.cjs"),t=require("../core/state.cjs"),n=require("./Validators.cjs"),r=require("../core/paths.cjs"),i=require("../infra/runtime.cjs"),a=require("../core/engine.cjs"),o=require("./Envapter.cjs"),s=require("../sources/FileSource.cjs");let c=require("node:process");c=e.__toESM(c,1);var l=class e extends o.Envapter{static{i.setRuntimeSink(e=>c.default.stderr.write(`${e}\n`)),e.useSource(new s.FileSource)}static set envPaths(e){r.assertFileApiSupported(`envPaths`,t.state.source);let i=Array.isArray(e)?e:[e];n.Validator.validateEnvFilesExist(i.map(e=>r.resolveAgainstBase(e)),e=>r.sourceFileExists(e)),t.state.envPaths=i,t.state.envPathsExplicitlySet=!0,a.refreshCache()}static get envPaths(){return t.state.envPaths}static set baseDir(e){let n=t.state.source;r.assertFileApiSupported(`baseDir`,n),t.state.baseDir=e===void 0?void 0:n.normalizeBaseDir(e),a.refreshCache()}static get baseDir(){return t.state.baseDir}static set envFileOptions(e){n.Validator.validateEnvFileOptions(e),t.state.userDefinedEnvFileOptions=e,a.refreshCache()}static get envFileOptions(){return t.state.userDefinedEnvFileOptions}static configureProfiles(e){r.assertFileApiSupported(`configureProfiles`,t.state.source),t.state.profiles=e,a.refreshCache()}static resetProfiles(){t.state.profiles=void 0,t.state.envPaths=[`.env`],t.state.envPathsExplicitlySet=!1,t.state.environmentExplicitlySet=!1,t.state.environment=void 0,a.refreshCache()}};exports.NodeEnvapter=l;
 //# sourceMappingURL=NodeEnvapter.cjs.map

package/dist/node/engine/NodeEnvapter.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"NodeEnvapter.cjs","names":["Envapter","process","NodeEnvSource","EnvapterBase"],"sources":["../../../src/engine/NodeEnvapter.ts"],"sourcesContent":["import process from 'node:process';\n\nimport { Envapter } from './Envapter';\nimport { Validator } from './Validators';\nimport { EnvapterBase } from '../core/EnvapterBase';\nimport { EnvironmentMethods } from '../core/EnvironmentMethods';\nimport { setRuntimeSink } from '../infra/runtime';\nimport { NodeEnvSource } from '../sources/NodeEnvSource';\n\nimport type { EnvFileOptions } from '../infra/Dotenv';\nimport type { ProfilesConfig } from '../types';\n\n/**\n * The Node/Bun/Deno facade: {@link Envapter} plus the filesystem-only configuration APIs (`.env`\n * path selection, base directory, dotenv options, and per-environment profiles). The browser and\n * Workers builds export the base {@link Envapter} without these, so calling one where there is no\n * filesystem is a compile error (and a thrown {@link EnvaptError} when types are bypassed).\n *\n * Writes target the state-owning class (`EnvapterBase`/`EnvironmentMethods`), not `this`: the engine\n * reads that state through `EnvapterBase`-anchored paths, so a subclass own-property would be invisible.\n * @public\n */\nexport class NodeEnvapter extends Envapter {\n    // A static block (not a top-level statement in a separate entry) keeps the bind intrinsic to this\n    // class: tree-shaken out of `import { EnvaptError }`, run whenever `Envapter` is referenced, with no\n    // sideEffects entry. Depends on the es2022 native static-block emit; lowering the target defeats it.\n    static {\n        setRuntimeSink((line) => process.stderr.write(`${line}\\n`));\n        NodeEnvapter.useSource(new NodeEnvSource());\n    }\n\n    /**\n     * Set custom .env file paths. Accepts either a single path or array of paths.\n     * Setting new paths clears the cache and reloads environment variables.\n     *\n     * When set, this takes absolute precedence. The dotenv-flow auto-cascade and any\n     * `Envapter.configureProfiles` configuration are ignored.\n     */\n    static set envPaths(paths: string[] | string) {\n        this.assertFileApiSupported('envPaths', EnvapterBase._source);\n        const newPaths = Array.isArray(paths) ? paths : [paths];\n        Validator.validateEnvFilesExist(\n            newPaths.map((p) => this.resolveAgainstBase(p)),\n            (p) => this.sourceFileExists(p)\n        );\n\n        EnvapterBase._envPaths = newPaths;\n        EnvapterBase._envPathsExplicitlySet = true;\n        this.refreshCache();\n    }\n\n    /**\n     * Get currently configured .env file paths\n     */\n    static get envPaths(): string[] {\n        return EnvapterBase._envPaths;\n    }\n\n    /**\n     * Set a base directory that relative `.env` paths resolve against instead of\n     * `process.cwd()`: the auto-cascade, `Envapter.configureProfiles` paths, and relative\n     * `envPaths`. Absolute paths always bypass it. Pass a directory, or a module URL\n     * (`import.meta.url`, ESM) / `import.meta.dirname` / `__dirname` (CJS) to anchor\n     * resolution next to the calling file regardless of launch directory.\n     *\n     * Set this before `envPaths` so relative `envPaths` validate against the right directory.\n     * Unset (`undefined`) restores `process.cwd()` resolution.\n     */\n    static set baseDir(value: string | URL | undefined) {\n        const source = EnvapterBase._source;\n        this.assertFileApiSupported('baseDir', source);\n        EnvapterBase._baseDir = value === undefined ? undefined : source.normalizeBaseDir(value);\n        this.refreshCache();\n    }\n\n    /** The configured base directory, or `undefined` when relative paths resolve against the working directory. */\n    static get baseDir(): string | undefined {\n        return EnvapterBase._baseDir;\n    }\n\n    /** Set the env file loader options (`encoding`, `override`). Refreshes the cache. */\n    static set envFileOptions(config: EnvFileOptions) {\n        Validator.validateEnvFileOptions(config);\n        EnvapterBase._userDefinedEnvFileOptions = config;\n        this.refreshCache();\n    }\n\n    /**\n     * Get current env file loader options\n     */\n    static get envFileOptions(): EnvFileOptions {\n        return EnvapterBase._userDefinedEnvFileOptions;\n    }\n\n    /**\n     * Configure per-environment `.env` path overrides on top of the dotenv-flow auto-cascade.\n     *\n     * When set, each `Environment` key's `paths` are loaded at higher precedence than the\n     * cascade for that environment. Unspecified environments still use the cascade as-is.\n     * Set `useDefaults: false` to disable the cascade entirely (load only the configured paths).\n     *\n     * Setting an explicit `Envapter.envPaths` value at any point overrides this configuration.\n     *\n     * @example\n     * ```ts\n     * Envapter.configureProfiles({\n     *   [Environment.Staging]: { paths: 'config/staging.env' },\n     *   [Environment.Production]: { paths: ['config/prod.env', 'secrets/prod.env'] }\n     * });\n     * ```\n     */\n    static configureProfiles(config: ProfilesConfig): void {\n        this.assertFileApiSupported('configureProfiles', EnvapterBase._source);\n        EnvironmentMethods._profiles = config;\n        this.refreshCache();\n    }\n\n    /**\n     * Reset all path-resolution configuration to defaults: clears any prior\n     * `Envapter.configureProfiles` call AND any explicit `Envapter.envPaths` assignment.\n     * Returns the resolver to the pure dotenv-flow cascade.\n     */\n    static resetProfiles(): void {\n        EnvironmentMethods._profiles = undefined;\n        EnvapterBase._envPaths = ['.env'];\n        EnvapterBase._envPathsExplicitlySet = false;\n        // Clear via `this`, not EnvironmentMethods: determineEnvironment writes `_environment*` via\n        // `this`, so a base-anchored clear would leave a subclass own-property shadowing it.\n        this._environmentExplicitlySet = false;\n        this._environment = undefined;\n        this.refreshCache();\n    }\n}\n"],"mappings":"4TAsBA,IAAa,EAAb,MAAa,UAAqBA,EAAAA,QAAS,CAIvC,OACI,EAAA,eAAgB,GAASC,EAAAA,QAAQ,OAAO,MAAM,GAAG,EAAK,GAAG,CAAC,EAC1D,EAAa,UAAU,IAAIC,EAAAA,aAAe,CAC9C,CASA,WAAW,SAAS,EAA0B,CAC1C,KAAK,uBAAuB,WAAYC,EAAAA,aAAa,OAAO,EAC5D,IAAM,EAAW,MAAM,QAAQ,CAAK,EAAI,EAAQ,CAAC,CAAK,EACtD,EAAA,UAAU,sBACN,EAAS,IAAK,GAAM,KAAK,mBAAmB,CAAC,CAAC,EAC7C,GAAM,KAAK,iBAAiB,CAAC,CAClC,EAEA,EAAA,aAAa,UAAY,EACzB,EAAA,aAAa,uBAAyB,GACtC,KAAK,aAAa,CACtB,CAKA,WAAW,UAAqB,CAC5B,OAAOA,EAAAA,aAAa,SACxB,CAYA,WAAW,QAAQ,EAAiC,CAChD,IAAM,EAASA,EAAAA,aAAa,QAC5B,KAAK,uBAAuB,UAAW,CAAM,EAC7C,EAAA,aAAa,SAAW,IAAU,IAAA,GAAY,IAAA,GAAY,EAAO,iBAAiB,CAAK,EACvF,KAAK,aAAa,CACtB,CAGA,WAAW,SAA8B,CACrC,OAAOA,EAAAA,aAAa,QACxB,CAGA,WAAW,eAAe,EAAwB,CAC9C,EAAA,UAAU,uBAAuB,CAAM,EACvC,EAAA,aAAa,2BAA6B,EAC1C,KAAK,aAAa,CACtB,CAKA,WAAW,gBAAiC,CACxC,OAAOA,EAAAA,aAAa,0BACxB,CAmBA,OAAO,kBAAkB,EAA8B,CACnD,KAAK,uBAAuB,oBAAqBA,EAAAA,aAAa,OAAO,EACrE,EAAA,mBAAmB,UAAY,EAC/B,KAAK,aAAa,CACtB,CAOA,OAAO,eAAsB,CACzB,EAAA,mBAAmB,UAAY,IAAA,GAC/B,EAAA,aAAa,UAAY,CAAC,MAAM,EAChC,EAAA,aAAa,uBAAyB,GAGtC,KAAK,0BAA4B,GACjC,KAAK,aAAe,IAAA,GACpB,KAAK,aAAa,CACtB,CACJ"}
+{"version":3,"file":"NodeEnvapter.cjs","names":["Envapter","process","FileSource","state","resolveAgainstBase","sourceFileExists"],"sources":["../../../src/engine/NodeEnvapter.ts"],"sourcesContent":["import process from 'node:process';\n\nimport { Envapter } from './Envapter';\nimport { Validator } from './Validators';\nimport { refreshCache } from '../core/engine';\nimport { assertFileApiSupported, resolveAgainstBase, sourceFileExists } from '../core/paths';\nimport { state } from '../core/state';\nimport { setRuntimeSink } from '../infra/runtime';\nimport { FileSource } from '../sources/FileSource';\n\nimport type { EnvFileOptions } from '../infra/Dotenv';\nimport type { ProfilesConfig } from '../types';\n\n/**\n * The Node/Bun/Deno facade: {@link Envapter} plus the filesystem-only configuration APIs (`.env`\n * path selection, base directory, dotenv options, and per-environment profiles). On the portable\n * build (Workers, the browser, edge) these same APIs warn once and no-op by default, controlled by\n * `Envapter.fileApiMode`.\n * @public\n */\nexport class NodeEnvapter extends Envapter {\n    // A static block (not a top-level statement in a separate entry) keeps the bind intrinsic to this\n    // class: tree-shaken out of `import { EnvaptError }`, run whenever `Envapter` is referenced, with no\n    // sideEffects entry. Depends on the es2022 native static-block emit.\n    static {\n        setRuntimeSink((line) => process.stderr.write(`${line}\\n`));\n        NodeEnvapter.useSource(new FileSource());\n    }\n\n    /**\n     * Set custom .env file paths. Accepts either a single path or array of paths.\n     * Setting new paths clears the cache and reloads environment variables.\n     *\n     * When set, this takes absolute precedence. The dotenv-flow auto-cascade and any\n     * `Envapter.configureProfiles` configuration are ignored.\n     */\n    static set envPaths(paths: string[] | string) {\n        assertFileApiSupported('envPaths', state.source);\n        const newPaths = Array.isArray(paths) ? paths : [paths];\n        Validator.validateEnvFilesExist(\n            newPaths.map((p) => resolveAgainstBase(p)),\n            (p) => sourceFileExists(p)\n        );\n\n        state.envPaths = newPaths;\n        state.envPathsExplicitlySet = true;\n        refreshCache();\n    }\n\n    /**\n     * Get currently configured .env file paths\n     */\n    static get envPaths(): string[] {\n        return state.envPaths;\n    }\n\n    /**\n     * Set a base directory that relative `.env` paths resolve against instead of\n     * `process.cwd()`: the auto-cascade, `Envapter.configureProfiles` paths, and relative\n     * `envPaths`. Absolute paths always bypass it. Pass a directory, or a module URL\n     * (`import.meta.url`, ESM) / `import.meta.dirname` / `__dirname` (CJS) to anchor\n     * resolution next to the calling file regardless of launch directory.\n     *\n     * Set this before `envPaths` so relative `envPaths` validate against the right directory.\n     * Unset (`undefined`) restores `process.cwd()` resolution.\n     */\n    static set baseDir(value: string | URL | undefined) {\n        const source = state.source;\n        assertFileApiSupported('baseDir', source);\n        state.baseDir = value === undefined ? undefined : source.normalizeBaseDir(value);\n        refreshCache();\n    }\n\n    /** The configured base directory, or `undefined` when relative paths resolve against the working directory. */\n    static get baseDir(): string | undefined {\n        return state.baseDir;\n    }\n\n    /** Set the env file loader options (`encoding`, `override`). Refreshes the cache. */\n    static set envFileOptions(config: EnvFileOptions) {\n        Validator.validateEnvFileOptions(config);\n        state.userDefinedEnvFileOptions = config;\n        refreshCache();\n    }\n\n    /**\n     * Get current env file loader options\n     */\n    static get envFileOptions(): EnvFileOptions {\n        return state.userDefinedEnvFileOptions;\n    }\n\n    /**\n     * Configure per-environment `.env` path overrides on top of the dotenv-flow auto-cascade.\n     *\n     * When set, each `Environment` key's `paths` are loaded at higher precedence than the\n     * cascade for that environment. Unspecified environments still use the cascade as-is.\n     * Set `useDefaults: false` to disable the cascade entirely (load only the configured paths).\n     *\n     * Setting an explicit `Envapter.envPaths` value at any point overrides this configuration.\n     *\n     * @example\n     * ```ts\n     * Envapter.configureProfiles({\n     *   [Environment.Staging]: { paths: 'config/staging.env' },\n     *   [Environment.Production]: { paths: ['config/prod.env', 'secrets/prod.env'] }\n     * });\n     * ```\n     */\n    static configureProfiles(config: ProfilesConfig): void {\n        assertFileApiSupported('configureProfiles', state.source);\n        state.profiles = config;\n        refreshCache();\n    }\n\n    /**\n     * Reset all path-resolution configuration to defaults: clears any prior\n     * `Envapter.configureProfiles` call AND any explicit `Envapter.envPaths` assignment.\n     * Returns the resolver to the pure dotenv-flow cascade.\n     */\n    static resetProfiles(): void {\n        state.profiles = undefined;\n        state.envPaths = ['.env'];\n        state.envPathsExplicitlySet = false;\n        state.environmentExplicitlySet = false;\n        state.environment = undefined;\n        refreshCache();\n    }\n}\n"],"mappings":"qUAoBA,IAAa,EAAb,MAAa,UAAqBA,EAAAA,QAAS,CAIvC,OACI,EAAA,eAAgB,GAASC,EAAAA,QAAQ,OAAO,MAAM,GAAG,EAAK,GAAG,CAAC,EAC1D,EAAa,UAAU,IAAIC,EAAAA,UAAY,CAC3C,CASA,WAAW,SAAS,EAA0B,CAC1C,EAAA,uBAAuB,WAAYC,EAAAA,MAAM,MAAM,EAC/C,IAAM,EAAW,MAAM,QAAQ,CAAK,EAAI,EAAQ,CAAC,CAAK,EACtD,EAAA,UAAU,sBACN,EAAS,IAAK,GAAMC,EAAAA,mBAAmB,CAAC,CAAC,EACxC,GAAMC,EAAAA,iBAAiB,CAAC,CAC7B,EAEA,EAAA,MAAM,SAAW,EACjB,EAAA,MAAM,sBAAwB,GAC9B,EAAA,aAAa,CACjB,CAKA,WAAW,UAAqB,CAC5B,OAAOF,EAAAA,MAAM,QACjB,CAYA,WAAW,QAAQ,EAAiC,CAChD,IAAM,EAASA,EAAAA,MAAM,OACrB,EAAA,uBAAuB,UAAW,CAAM,EACxC,EAAA,MAAM,QAAU,IAAU,IAAA,GAAY,IAAA,GAAY,EAAO,iBAAiB,CAAK,EAC/E,EAAA,aAAa,CACjB,CAGA,WAAW,SAA8B,CACrC,OAAOA,EAAAA,MAAM,OACjB,CAGA,WAAW,eAAe,EAAwB,CAC9C,EAAA,UAAU,uBAAuB,CAAM,EACvC,EAAA,MAAM,0BAA4B,EAClC,EAAA,aAAa,CACjB,CAKA,WAAW,gBAAiC,CACxC,OAAOA,EAAAA,MAAM,yBACjB,CAmBA,OAAO,kBAAkB,EAA8B,CACnD,EAAA,uBAAuB,oBAAqBA,EAAAA,MAAM,MAAM,EACxD,EAAA,MAAM,SAAW,EACjB,EAAA,aAAa,CACjB,CAOA,OAAO,eAAsB,CACzB,EAAA,MAAM,SAAW,IAAA,GACjB,EAAA,MAAM,SAAW,CAAC,MAAM,EACxB,EAAA,MAAM,sBAAwB,GAC9B,EAAA,MAAM,yBAA2B,GACjC,EAAA,MAAM,YAAc,IAAA,GACpB,EAAA,aAAa,CACjB,CACJ"}

package/dist/node/engine/NodeEnvapter.mjs

@@ -1,2 +1,2 @@
-import{Validator as e}from"./Validators.mjs";import{setRuntimeSink as t}from"../infra/runtime.mjs";import{EnvapterBase as n}from"../core/EnvapterBase.mjs";import{EnvironmentMethods as r}from"../core/EnvironmentMethods.mjs";import{Envapter as i}from"./Envapter.mjs";import{NodeEnvSource as a}from"../sources/NodeEnvSource.mjs";import o from"node:process";var s=class s extends i{static{t(e=>o.stderr.write(`${e}\n`)),s.useSource(new a)}static set envPaths(t){this.assertFileApiSupported(`envPaths`,n._source);let r=Array.isArray(t)?t:[t];e.validateEnvFilesExist(r.map(e=>this.resolveAgainstBase(e)),e=>this.sourceFileExists(e)),n._envPaths=r,n._envPathsExplicitlySet=!0,this.refreshCache()}static get envPaths(){return n._envPaths}static set baseDir(e){let t=n._source;this.assertFileApiSupported(`baseDir`,t),n._baseDir=e===void 0?void 0:t.normalizeBaseDir(e),this.refreshCache()}static get baseDir(){return n._baseDir}static set envFileOptions(t){e.validateEnvFileOptions(t),n._userDefinedEnvFileOptions=t,this.refreshCache()}static get envFileOptions(){return n._userDefinedEnvFileOptions}static configureProfiles(e){this.assertFileApiSupported(`configureProfiles`,n._source),r._profiles=e,this.refreshCache()}static resetProfiles(){r._profiles=void 0,n._envPaths=[`.env`],n._envPathsExplicitlySet=!1,this._environmentExplicitlySet=!1,this._environment=void 0,this.refreshCache()}};export{s as NodeEnvapter};
+import{state as e}from"../core/state.mjs";import{Validator as t}from"./Validators.mjs";import{assertFileApiSupported as n,resolveAgainstBase as r,sourceFileExists as i}from"../core/paths.mjs";import{setRuntimeSink as a}from"../infra/runtime.mjs";import{refreshCache as o}from"../core/engine.mjs";import{Envapter as s}from"./Envapter.mjs";import{FileSource as c}from"../sources/FileSource.mjs";import l from"node:process";var u=class u extends s{static{a(e=>l.stderr.write(`${e}\n`)),u.useSource(new c)}static set envPaths(a){n(`envPaths`,e.source);let s=Array.isArray(a)?a:[a];t.validateEnvFilesExist(s.map(e=>r(e)),e=>i(e)),e.envPaths=s,e.envPathsExplicitlySet=!0,o()}static get envPaths(){return e.envPaths}static set baseDir(t){let r=e.source;n(`baseDir`,r),e.baseDir=t===void 0?void 0:r.normalizeBaseDir(t),o()}static get baseDir(){return e.baseDir}static set envFileOptions(n){t.validateEnvFileOptions(n),e.userDefinedEnvFileOptions=n,o()}static get envFileOptions(){return e.userDefinedEnvFileOptions}static configureProfiles(t){n(`configureProfiles`,e.source),e.profiles=t,o()}static resetProfiles(){e.profiles=void 0,e.envPaths=[`.env`],e.envPathsExplicitlySet=!1,e.environmentExplicitlySet=!1,e.environment=void 0,o()}};export{u as NodeEnvapter};
 //# sourceMappingURL=NodeEnvapter.mjs.map

package/dist/node/engine/NodeEnvapter.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"NodeEnvapter.mjs","names":[],"sources":["../../../src/engine/NodeEnvapter.ts"],"sourcesContent":["import process from 'node:process';\n\nimport { Envapter } from './Envapter';\nimport { Validator } from './Validators';\nimport { EnvapterBase } from '../core/EnvapterBase';\nimport { EnvironmentMethods } from '../core/EnvironmentMethods';\nimport { setRuntimeSink } from '../infra/runtime';\nimport { NodeEnvSource } from '../sources/NodeEnvSource';\n\nimport type { EnvFileOptions } from '../infra/Dotenv';\nimport type { ProfilesConfig } from '../types';\n\n/**\n * The Node/Bun/Deno facade: {@link Envapter} plus the filesystem-only configuration APIs (`.env`\n * path selection, base directory, dotenv options, and per-environment profiles). The browser and\n * Workers builds export the base {@link Envapter} without these, so calling one where there is no\n * filesystem is a compile error (and a thrown {@link EnvaptError} when types are bypassed).\n *\n * Writes target the state-owning class (`EnvapterBase`/`EnvironmentMethods`), not `this`: the engine\n * reads that state through `EnvapterBase`-anchored paths, so a subclass own-property would be invisible.\n * @public\n */\nexport class NodeEnvapter extends Envapter {\n    // A static block (not a top-level statement in a separate entry) keeps the bind intrinsic to this\n    // class: tree-shaken out of `import { EnvaptError }`, run whenever `Envapter` is referenced, with no\n    // sideEffects entry. Depends on the es2022 native static-block emit; lowering the target defeats it.\n    static {\n        setRuntimeSink((line) => process.stderr.write(`${line}\\n`));\n        NodeEnvapter.useSource(new NodeEnvSource());\n    }\n\n    /**\n     * Set custom .env file paths. Accepts either a single path or array of paths.\n     * Setting new paths clears the cache and reloads environment variables.\n     *\n     * When set, this takes absolute precedence. The dotenv-flow auto-cascade and any\n     * `Envapter.configureProfiles` configuration are ignored.\n     */\n    static set envPaths(paths: string[] | string) {\n        this.assertFileApiSupported('envPaths', EnvapterBase._source);\n        const newPaths = Array.isArray(paths) ? paths : [paths];\n        Validator.validateEnvFilesExist(\n            newPaths.map((p) => this.resolveAgainstBase(p)),\n            (p) => this.sourceFileExists(p)\n        );\n\n        EnvapterBase._envPaths = newPaths;\n        EnvapterBase._envPathsExplicitlySet = true;\n        this.refreshCache();\n    }\n\n    /**\n     * Get currently configured .env file paths\n     */\n    static get envPaths(): string[] {\n        return EnvapterBase._envPaths;\n    }\n\n    /**\n     * Set a base directory that relative `.env` paths resolve against instead of\n     * `process.cwd()`: the auto-cascade, `Envapter.configureProfiles` paths, and relative\n     * `envPaths`. Absolute paths always bypass it. Pass a directory, or a module URL\n     * (`import.meta.url`, ESM) / `import.meta.dirname` / `__dirname` (CJS) to anchor\n     * resolution next to the calling file regardless of launch directory.\n     *\n     * Set this before `envPaths` so relative `envPaths` validate against the right directory.\n     * Unset (`undefined`) restores `process.cwd()` resolution.\n     */\n    static set baseDir(value: string | URL | undefined) {\n        const source = EnvapterBase._source;\n        this.assertFileApiSupported('baseDir', source);\n        EnvapterBase._baseDir = value === undefined ? undefined : source.normalizeBaseDir(value);\n        this.refreshCache();\n    }\n\n    /** The configured base directory, or `undefined` when relative paths resolve against the working directory. */\n    static get baseDir(): string | undefined {\n        return EnvapterBase._baseDir;\n    }\n\n    /** Set the env file loader options (`encoding`, `override`). Refreshes the cache. */\n    static set envFileOptions(config: EnvFileOptions) {\n        Validator.validateEnvFileOptions(config);\n        EnvapterBase._userDefinedEnvFileOptions = config;\n        this.refreshCache();\n    }\n\n    /**\n     * Get current env file loader options\n     */\n    static get envFileOptions(): EnvFileOptions {\n        return EnvapterBase._userDefinedEnvFileOptions;\n    }\n\n    /**\n     * Configure per-environment `.env` path overrides on top of the dotenv-flow auto-cascade.\n     *\n     * When set, each `Environment` key's `paths` are loaded at higher precedence than the\n     * cascade for that environment. Unspecified environments still use the cascade as-is.\n     * Set `useDefaults: false` to disable the cascade entirely (load only the configured paths).\n     *\n     * Setting an explicit `Envapter.envPaths` value at any point overrides this configuration.\n     *\n     * @example\n     * ```ts\n     * Envapter.configureProfiles({\n     *   [Environment.Staging]: { paths: 'config/staging.env' },\n     *   [Environment.Production]: { paths: ['config/prod.env', 'secrets/prod.env'] }\n     * });\n     * ```\n     */\n    static configureProfiles(config: ProfilesConfig): void {\n        this.assertFileApiSupported('configureProfiles', EnvapterBase._source);\n        EnvironmentMethods._profiles = config;\n        this.refreshCache();\n    }\n\n    /**\n     * Reset all path-resolution configuration to defaults: clears any prior\n     * `Envapter.configureProfiles` call AND any explicit `Envapter.envPaths` assignment.\n     * Returns the resolver to the pure dotenv-flow cascade.\n     */\n    static resetProfiles(): void {\n        EnvironmentMethods._profiles = undefined;\n        EnvapterBase._envPaths = ['.env'];\n        EnvapterBase._envPathsExplicitlySet = false;\n        // Clear via `this`, not EnvironmentMethods: determineEnvironment writes `_environment*` via\n        // `this`, so a base-anchored clear would leave a subclass own-property shadowing it.\n        this._environmentExplicitlySet = false;\n        this._environment = undefined;\n        this.refreshCache();\n    }\n}\n"],"mappings":"kWAsBA,IAAa,EAAb,MAAa,UAAqB,CAAS,CAIvC,OACI,EAAgB,GAAS,EAAQ,OAAO,MAAM,GAAG,EAAK,GAAG,CAAC,EAC1D,EAAa,UAAU,IAAI,CAAe,CAC9C,CASA,WAAW,SAAS,EAA0B,CAC1C,KAAK,uBAAuB,WAAY,EAAa,OAAO,EAC5D,IAAM,EAAW,MAAM,QAAQ,CAAK,EAAI,EAAQ,CAAC,CAAK,EACtD,EAAU,sBACN,EAAS,IAAK,GAAM,KAAK,mBAAmB,CAAC,CAAC,EAC7C,GAAM,KAAK,iBAAiB,CAAC,CAClC,EAEA,EAAa,UAAY,EACzB,EAAa,uBAAyB,GACtC,KAAK,aAAa,CACtB,CAKA,WAAW,UAAqB,CAC5B,OAAO,EAAa,SACxB,CAYA,WAAW,QAAQ,EAAiC,CAChD,IAAM,EAAS,EAAa,QAC5B,KAAK,uBAAuB,UAAW,CAAM,EAC7C,EAAa,SAAW,IAAU,IAAA,GAAY,IAAA,GAAY,EAAO,iBAAiB,CAAK,EACvF,KAAK,aAAa,CACtB,CAGA,WAAW,SAA8B,CACrC,OAAO,EAAa,QACxB,CAGA,WAAW,eAAe,EAAwB,CAC9C,EAAU,uBAAuB,CAAM,EACvC,EAAa,2BAA6B,EAC1C,KAAK,aAAa,CACtB,CAKA,WAAW,gBAAiC,CACxC,OAAO,EAAa,0BACxB,CAmBA,OAAO,kBAAkB,EAA8B,CACnD,KAAK,uBAAuB,oBAAqB,EAAa,OAAO,EACrE,EAAmB,UAAY,EAC/B,KAAK,aAAa,CACtB,CAOA,OAAO,eAAsB,CACzB,EAAmB,UAAY,IAAA,GAC/B,EAAa,UAAY,CAAC,MAAM,EAChC,EAAa,uBAAyB,GAGtC,KAAK,0BAA4B,GACjC,KAAK,aAAe,IAAA,GACpB,KAAK,aAAa,CACtB,CACJ"}
+{"version":3,"file":"NodeEnvapter.mjs","names":[],"sources":["../../../src/engine/NodeEnvapter.ts"],"sourcesContent":["import process from 'node:process';\n\nimport { Envapter } from './Envapter';\nimport { Validator } from './Validators';\nimport { refreshCache } from '../core/engine';\nimport { assertFileApiSupported, resolveAgainstBase, sourceFileExists } from '../core/paths';\nimport { state } from '../core/state';\nimport { setRuntimeSink } from '../infra/runtime';\nimport { FileSource } from '../sources/FileSource';\n\nimport type { EnvFileOptions } from '../infra/Dotenv';\nimport type { ProfilesConfig } from '../types';\n\n/**\n * The Node/Bun/Deno facade: {@link Envapter} plus the filesystem-only configuration APIs (`.env`\n * path selection, base directory, dotenv options, and per-environment profiles). On the portable\n * build (Workers, the browser, edge) these same APIs warn once and no-op by default, controlled by\n * `Envapter.fileApiMode`.\n * @public\n */\nexport class NodeEnvapter extends Envapter {\n    // A static block (not a top-level statement in a separate entry) keeps the bind intrinsic to this\n    // class: tree-shaken out of `import { EnvaptError }`, run whenever `Envapter` is referenced, with no\n    // sideEffects entry. Depends on the es2022 native static-block emit.\n    static {\n        setRuntimeSink((line) => process.stderr.write(`${line}\\n`));\n        NodeEnvapter.useSource(new FileSource());\n    }\n\n    /**\n     * Set custom .env file paths. Accepts either a single path or array of paths.\n     * Setting new paths clears the cache and reloads environment variables.\n     *\n     * When set, this takes absolute precedence. The dotenv-flow auto-cascade and any\n     * `Envapter.configureProfiles` configuration are ignored.\n     */\n    static set envPaths(paths: string[] | string) {\n        assertFileApiSupported('envPaths', state.source);\n        const newPaths = Array.isArray(paths) ? paths : [paths];\n        Validator.validateEnvFilesExist(\n            newPaths.map((p) => resolveAgainstBase(p)),\n            (p) => sourceFileExists(p)\n        );\n\n        state.envPaths = newPaths;\n        state.envPathsExplicitlySet = true;\n        refreshCache();\n    }\n\n    /**\n     * Get currently configured .env file paths\n     */\n    static get envPaths(): string[] {\n        return state.envPaths;\n    }\n\n    /**\n     * Set a base directory that relative `.env` paths resolve against instead of\n     * `process.cwd()`: the auto-cascade, `Envapter.configureProfiles` paths, and relative\n     * `envPaths`. Absolute paths always bypass it. Pass a directory, or a module URL\n     * (`import.meta.url`, ESM) / `import.meta.dirname` / `__dirname` (CJS) to anchor\n     * resolution next to the calling file regardless of launch directory.\n     *\n     * Set this before `envPaths` so relative `envPaths` validate against the right directory.\n     * Unset (`undefined`) restores `process.cwd()` resolution.\n     */\n    static set baseDir(value: string | URL | undefined) {\n        const source = state.source;\n        assertFileApiSupported('baseDir', source);\n        state.baseDir = value === undefined ? undefined : source.normalizeBaseDir(value);\n        refreshCache();\n    }\n\n    /** The configured base directory, or `undefined` when relative paths resolve against the working directory. */\n    static get baseDir(): string | undefined {\n        return state.baseDir;\n    }\n\n    /** Set the env file loader options (`encoding`, `override`). Refreshes the cache. */\n    static set envFileOptions(config: EnvFileOptions) {\n        Validator.validateEnvFileOptions(config);\n        state.userDefinedEnvFileOptions = config;\n        refreshCache();\n    }\n\n    /**\n     * Get current env file loader options\n     */\n    static get envFileOptions(): EnvFileOptions {\n        return state.userDefinedEnvFileOptions;\n    }\n\n    /**\n     * Configure per-environment `.env` path overrides on top of the dotenv-flow auto-cascade.\n     *\n     * When set, each `Environment` key's `paths` are loaded at higher precedence than the\n     * cascade for that environment. Unspecified environments still use the cascade as-is.\n     * Set `useDefaults: false` to disable the cascade entirely (load only the configured paths).\n     *\n     * Setting an explicit `Envapter.envPaths` value at any point overrides this configuration.\n     *\n     * @example\n     * ```ts\n     * Envapter.configureProfiles({\n     *   [Environment.Staging]: { paths: 'config/staging.env' },\n     *   [Environment.Production]: { paths: ['config/prod.env', 'secrets/prod.env'] }\n     * });\n     * ```\n     */\n    static configureProfiles(config: ProfilesConfig): void {\n        assertFileApiSupported('configureProfiles', state.source);\n        state.profiles = config;\n        refreshCache();\n    }\n\n    /**\n     * Reset all path-resolution configuration to defaults: clears any prior\n     * `Envapter.configureProfiles` call AND any explicit `Envapter.envPaths` assignment.\n     * Returns the resolver to the pure dotenv-flow cascade.\n     */\n    static resetProfiles(): void {\n        state.profiles = undefined;\n        state.envPaths = ['.env'];\n        state.envPathsExplicitlySet = false;\n        state.environmentExplicitlySet = false;\n        state.environment = undefined;\n        refreshCache();\n    }\n}\n"],"mappings":"qaAoBA,IAAa,EAAb,MAAa,UAAqB,CAAS,CAIvC,OACI,EAAgB,GAAS,EAAQ,OAAO,MAAM,GAAG,EAAK,GAAG,CAAC,EAC1D,EAAa,UAAU,IAAI,CAAY,CAC3C,CASA,WAAW,SAAS,EAA0B,CAC1C,EAAuB,WAAY,EAAM,MAAM,EAC/C,IAAM,EAAW,MAAM,QAAQ,CAAK,EAAI,EAAQ,CAAC,CAAK,EACtD,EAAU,sBACN,EAAS,IAAK,GAAM,EAAmB,CAAC,CAAC,EACxC,GAAM,EAAiB,CAAC,CAC7B,EAEA,EAAM,SAAW,EACjB,EAAM,sBAAwB,GAC9B,EAAa,CACjB,CAKA,WAAW,UAAqB,CAC5B,OAAO,EAAM,QACjB,CAYA,WAAW,QAAQ,EAAiC,CAChD,IAAM,EAAS,EAAM,OACrB,EAAuB,UAAW,CAAM,EACxC,EAAM,QAAU,IAAU,IAAA,GAAY,IAAA,GAAY,EAAO,iBAAiB,CAAK,EAC/E,EAAa,CACjB,CAGA,WAAW,SAA8B,CACrC,OAAO,EAAM,OACjB,CAGA,WAAW,eAAe,EAAwB,CAC9C,EAAU,uBAAuB,CAAM,EACvC,EAAM,0BAA4B,EAClC,EAAa,CACjB,CAKA,WAAW,gBAAiC,CACxC,OAAO,EAAM,yBACjB,CAmBA,OAAO,kBAAkB,EAA8B,CACnD,EAAuB,oBAAqB,EAAM,MAAM,EACxD,EAAM,SAAW,EACjB,EAAa,CACjB,CAOA,OAAO,eAAsB,CACzB,EAAM,SAAW,IAAA,GACjB,EAAM,SAAW,CAAC,MAAM,EACxB,EAAM,sBAAwB,GAC9B,EAAM,yBAA2B,GACjC,EAAM,YAAc,IAAA,GACpB,EAAa,CACjB,CACJ"}

package/dist/node/engine/TemplateResolver.cjs

@@ -1,2 +1,2 @@
-const e=require("../infra/Error.cjs"),t=require("../infra/Debug.cjs");var n=class{envService;TEMPLATE_REGEX=/\${\w*}/g;constructor(e){this.envService=e}resolveTemplate(n,r,i=new Set){i.add(n);let a=this.envService.isStrict(),o=r.replace(this.TEMPLATE_REGEX,r=>{let o=r.slice(2,-1);if(i.has(o))return r;let s=this.envService.getRaw(o);if(s===void 0||s===``||a&&s.trim()===``){if(a)throw new e.EnvaptError(305,`Cannot resolve template variable "\${${o}}": value is missing or empty.`);return t.debugWarn(`unresolved template \${${o}} preserved as literal`),r}let c=this.resolveTemplate(o,s,new Set(i));return c.includes(`\${${n}}`)||c===s&&/\$\{[^}]*\}/.test(c)?r:c});return i.delete(n),o}};exports.TemplateResolver=n;
+const e=require("../infra/Error.cjs"),t=require("../core/state.cjs"),n=require("../infra/Debug.cjs");var r=class{envService;TEMPLATE_REGEX=/\${\w*}/g;constructor(e){this.envService=e}resolveTemplate(r,i,a=new Set){a.add(r);let o=t.state.strict,s=i.replace(this.TEMPLATE_REGEX,t=>{let i=t.slice(2,-1);if(a.has(i))return t;let s=this.envService.getRaw(i);if(s===void 0||s===``||o&&s.trim()===``){if(o)throw new e.EnvaptError(305,`Cannot resolve template variable "\${${i}}": value is missing or empty.`);return n.debugWarn(`unresolved template \${${i}} preserved as literal`),t}let c=this.resolveTemplate(i,s,new Set(a));return c.includes(`\${${r}}`)||c===s&&/\$\{[^}]*\}/.test(c)?t:c});return a.delete(r),s}};exports.TemplateResolver=r;
 //# sourceMappingURL=TemplateResolver.cjs.map

package/dist/node/engine/TemplateResolver.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"TemplateResolver.cjs","names":["EnvaptError"],"sources":["../../../src/engine/TemplateResolver.ts"],"sourcesContent":["import { 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 = this.envService.isStrict();\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":"sEAUA,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,KAAK,WAAW,SAAS,EAElC,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,IAAIA,EAAAA,YAAAA,IAEN,wCAAwC,EAAS,+BACrD,EAGJ,OADA,EAAA,UAAU,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.cjs","names":["state","EnvaptError"],"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":"qGAWA,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,EAASA,EAAAA,MAAM,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,IAAIC,EAAAA,YAAAA,IAEN,wCAAwC,EAAS,+BACrD,EAGJ,OADA,EAAA,UAAU,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/node/engine/TemplateResolver.mjs

@@ -1,2 +1,2 @@
-import{EnvaptError as e}from"../infra/Error.mjs";import{debugWarn as t}from"../infra/Debug.mjs";var n=class{envService;TEMPLATE_REGEX=/\${\w*}/g;constructor(e){this.envService=e}resolveTemplate(n,r,i=new Set){i.add(n);let a=this.envService.isStrict(),o=r.replace(this.TEMPLATE_REGEX,r=>{let o=r.slice(2,-1);if(i.has(o))return r;let s=this.envService.getRaw(o);if(s===void 0||s===``||a&&s.trim()===``){if(a)throw new e(305,`Cannot resolve template variable "\${${o}}": value is missing or empty.`);return t(`unresolved template \${${o}} preserved as literal`),r}let c=this.resolveTemplate(o,s,new Set(i));return c.includes(`\${${n}}`)||c===s&&/\$\{[^}]*\}/.test(c)?r:c});return i.delete(n),o}};export{n as TemplateResolver};
+import{EnvaptError as e}from"../infra/Error.mjs";import{state as t}from"../core/state.mjs";import{debugWarn as n}from"../infra/Debug.mjs";var r=class{envService;TEMPLATE_REGEX=/\${\w*}/g;constructor(e){this.envService=e}resolveTemplate(r,i,a=new Set){a.add(r);let o=t.strict,s=i.replace(this.TEMPLATE_REGEX,t=>{let i=t.slice(2,-1);if(a.has(i))return t;let s=this.envService.getRaw(i);if(s===void 0||s===``||o&&s.trim()===``){if(o)throw new e(305,`Cannot resolve template variable "\${${i}}": value is missing or empty.`);return n(`unresolved template \${${i}} preserved as literal`),t}let c=this.resolveTemplate(i,s,new Set(a));return c.includes(`\${${r}}`)||c===s&&/\$\{[^}]*\}/.test(c)?t:c});return a.delete(r),s}};export{r as TemplateResolver};
 //# sourceMappingURL=TemplateResolver.mjs.map

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

@@ -1 +1 @@
-{"version":3,"file":"TemplateResolver.mjs","names":[],"sources":["../../../src/engine/TemplateResolver.ts"],"sourcesContent":["import { 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 = this.envService.isStrict();\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":"gGAUA,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,KAAK,WAAW,SAAS,EAElC,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 { 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"}

package/dist/node/engine/Validators.cjs

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

package/dist/node/engine/Validators.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"Validators.cjs","names":["ListOfBuiltInConverters","isArrayOf","EnvaptError","BuiltInConverterTypeCheckers"],"sources":["../../../src/engine/Validators.ts"],"sourcesContent":["// Import the converter modules directly, not via the `./converters` barrel: that barrel pulls in\n// ValueConverter, which imports this Validator, so a barrel import here would cycle.\nimport { isArrayOf } from '../converters/Converters';\nimport { ListOfBuiltInConverters, BuiltInConverterTypeCheckers } from '../converters/ListOfBuiltInConverters';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { ArrayOf, ConverterToken } from '../converters/Converters';\nimport type { EnvFileOptions } from '../infra/Dotenv';\nimport type { StandardSchemaV1 } from '../infra/StandardSchema';\nimport type { BuiltInConverter, ConverterFunction, EnvaptConverter } from '../types';\n\n// eslint-disable-next-line @typescript-eslint/no-extraneous-class -- cohesive dispatch of stateless type guards, same shape as BuiltInConverters\nexport class Validator {\n    /**\n     * Check if a value is a built-in scalar converter token\n     */\n    static isBuiltInConverter<TFallback>(value: EnvaptConverter<TFallback>): value is BuiltInConverter {\n        if (typeof value === 'string') return ListOfBuiltInConverters.includes(value);\n        return false;\n    }\n\n    /**\n     * Check if a value is an `ArrayOf<...>` token produced by {@link Converters.array}.\n     */\n    static isArrayConverter(value: unknown): value is ArrayOf {\n        return isArrayOf(value);\n    }\n\n    // Structural check: `version === 1` + callable `validate` is the minimum dispatchable\n    // shape per the Standard Schema spec.\n    static isStandardSchema(value: unknown): value is StandardSchemaV1 {\n        if (typeof value !== 'object' || value === null) return false;\n        if (!('~standard' in value)) return false;\n        const slot = value['~standard'];\n        if (typeof slot !== 'object' || slot === null) return false;\n        const props = slot as { version?: unknown; validate?: unknown };\n        return props.version === 1 && typeof props.validate === 'function';\n    }\n\n    static customConvertor<TFallback>(\n        converter: EnvaptConverter<TFallback>\n    ): asserts converter is ConverterFunction<TFallback> {\n        if (typeof converter !== 'function') {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidCustomConverter,\n                `Custom converter must be a function, got ${typeof converter}.`\n            );\n        }\n    }\n\n    /**\n     * Runtime validation that the `ArrayOf<...>` configuration is well-formed.\n     */\n    static arrayConverter(value: unknown): asserts value is ArrayOf {\n        if (!isArrayOf(value)) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidArrayConverterType,\n                'Expected an ArrayOf<...> token produced by Converters.array(...)'\n            );\n        }\n\n        if (typeof value.delimiter !== 'string' || value.delimiter.length === 0) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.MissingDelimiter,\n                `ArrayOf<...> requires a non-empty string delimiter, got ${typeof value.delimiter}`\n            );\n        }\n\n        const elementOf = value.of;\n        const isScalar = typeof elementOf === 'string' && ListOfBuiltInConverters.includes(elementOf);\n        const isCustomFn = typeof elementOf === 'function';\n        if (!isScalar && !isCustomFn) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidArrayConverterType,\n                `ArrayOf<...> element (\"of\") must be a built-in scalar token or a function, got ${typeof elementOf}`\n            );\n        }\n    }\n\n    /**\n     * Validate that a string is a valid built-in scalar converter token\n     */\n    static builtInConverter(value: unknown): asserts value is BuiltInConverter {\n        if (typeof value !== 'string') {\n            throw new EnvaptError(EnvaptErrorCodes.InvalidConverterType, `Expected string, got ${typeof value}`);\n        }\n\n        if (!ListOfBuiltInConverters.includes(value as ConverterToken)) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidBuiltInConverter,\n                `\"${value}\" is not a valid converter type. Valid types are: ${ListOfBuiltInConverters.join(',')}`\n            );\n        }\n    }\n\n    /**\n     * Validate that fallback type matches the converter's return type for built-in converters\n     */\n    static validateBuiltInConverterFallback(converter: BuiltInConverter, fallback: unknown): void {\n        const typeChecker = BuiltInConverterTypeCheckers[converter];\n        if (!typeChecker(fallback)) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.FallbackConverterTypeMismatch,\n                `Fallback type does not match converter \"${converter}\". Expected ${converter} compatible type.`\n            );\n        }\n    }\n\n    /**\n     * Validate that all elements in an array fallback have consistent types\n     */\n    static validateArrayFallbackElementTypes(fallback: unknown[]): void {\n        if (fallback.length === 0) return;\n\n        const firstElementType = typeof fallback[0];\n        const hasInconsistentTypes = fallback.some((element, index) => {\n            if (index === 0) return false;\n            return typeof element !== firstElementType;\n        });\n\n        if (hasInconsistentTypes) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.ArrayFallbackElementTypeMismatch,\n                `All elements in array fallback must have the same type. Found mixed types.`\n            );\n        }\n    }\n\n    /**\n     * Validate that an `ArrayOf<...>` element converter matches the runtime types of its\n     * fallback elements. For `Converters.Time` arrays the element-time-string format is also\n     * checked here.\n     */\n    static validateArrayConverterElementTypeMatch(elementOf: ArrayOf['of'], fallback: unknown[]): void {\n        if (fallback.length === 0) return;\n\n        if (typeof elementOf === 'function') {\n            // Custom element converters can return anything; we can't statically validate the fallback shape.\n            return;\n        }\n\n        const elementToken = elementOf;\n\n        // Time array fallbacks may be number[] OR string[] (TimeFallback[]).\n        if (elementToken === 'time') {\n            const everyNumber = fallback.every((v) => typeof v === 'number');\n            const everyString = fallback.every((v) => typeof v === 'string');\n            if (!everyNumber && !everyString) {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.ArrayFallbackElementTypeMismatch,\n                    'Time array fallback must be all numbers or all time-string entries.'\n                );\n            }\n            return;\n        }\n\n        const typeChecker = BuiltInConverterTypeCheckers[elementToken];\n        const firstElement = fallback[0];\n        if (!typeChecker(firstElement)) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.ArrayFallbackElementTypeMismatch,\n                `Array converter type \"${elementToken}\" does not match fallback element type. Expected ${elementToken} compatible elements.`\n            );\n        }\n    }\n\n    /**\n     * Check if a value is a primitive constructor\n     */\n    static isPrimitiveConstructor(\n        value: unknown\n    ): value is typeof String | typeof Number | typeof Boolean | typeof BigInt | typeof Symbol {\n        return value === String || value === Number || value === Boolean || value === BigInt || value === Symbol;\n    }\n\n    /**\n     * Safely coerce a fallback value using a primitive constructor\n     */\n    static coercePrimitiveFallback<CoercedType>(\n        converter: typeof String | typeof Number | typeof Boolean | typeof BigInt | typeof Symbol,\n        fallback: unknown\n    ): CoercedType {\n        if (this.isCorrectPrimitiveType(converter, fallback)) return fallback as CoercedType;\n        return this.performPrimitiveCoercion<CoercedType>(converter, fallback);\n    }\n\n    private static isCorrectPrimitiveType(\n        converter: typeof String | typeof Number | typeof Boolean | typeof BigInt | typeof Symbol,\n        fallback: unknown\n    ): boolean {\n        if (converter === String && typeof fallback === 'string') return true;\n        if (converter === Number && typeof fallback === 'number') return true;\n        if (converter === Boolean && typeof fallback === 'boolean') return true;\n        if (converter === BigInt && typeof fallback === 'bigint') return true;\n        if (converter === Symbol && typeof fallback === 'symbol') return true;\n        return false;\n    }\n\n    private static performPrimitiveCoercion<CoercedType>(\n        converter: typeof String | typeof Number | typeof Boolean | typeof BigInt | typeof Symbol,\n        fallback: unknown\n    ): CoercedType {\n        try {\n            if (converter === String) return String(fallback) as CoercedType;\n            if (converter === Number) return Number(fallback) as CoercedType;\n            if (converter === Boolean) return Boolean(fallback) as CoercedType;\n            if (converter === BigInt) return BigInt(fallback as string | number | bigint) as CoercedType;\n            /* v8 ignore next -- @preserve */\n            if (converter === Symbol) return Symbol.for(String(fallback)) as CoercedType;\n        } catch (error) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.PrimitiveCoercionFailed,\n                `Failed to coerce fallback value using ${converter.name}: ${(error as Error).message}`\n            );\n        }\n\n        /* v8 ignore next -- @preserve */\n        throw new EnvaptError(\n            EnvaptErrorCodes.PrimitiveCoercionFailed,\n            `Unknown primitive converter: ${converter.name}`\n        );\n    }\n\n    /**\n     * Reject non-boolean inputs to `Envapter.syncProcessEnv` so a truthy typo\n     * (`'true'`, `1`, etc.) does not silently enable the mirror.\n     */\n    static validateSyncProcessEnv(value: unknown): asserts value is boolean {\n        if (typeof value !== 'boolean') {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidUserDefinedConfig,\n                `Envapter.syncProcessEnv must be a boolean, got ${typeof value}.`\n            );\n        }\n    }\n\n    /**\n     * Make sure the user hasn't provided prohibited options in their dotenv config\n     */\n    static validateEnvFileOptions(config: object): config is EnvFileOptions {\n        const validKeys = new Set(['encoding', 'override']);\n        const invalidKeys = Object.keys(config).filter((key) => !validKeys.has(key));\n\n        if (invalidKeys.length > 0) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidUserDefinedConfig,\n                `Invalid envFileOptions: ${invalidKeys.join(', ')}. Allowed options: ${Array.from(validKeys).join(', ')}. For debug output, use Envapter.debug or the ENVAPT_DEBUG env var.`\n            );\n        }\n\n        return true;\n    }\n\n    // Existence is probed through the caller-supplied `fileExists` (backed by the bound source) so\n    // this stays free of `node:fs`.\n    static validateEnvFilesExist(paths: string[], fileExists: (path: string) => boolean): void {\n        const missing = paths.filter((p) => !fileExists(p));\n\n        if (missing.length > 0) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.EnvFilesNotFound,\n                `Environment file not found at path: ${missing.join(', ')}`\n            );\n        }\n    }\n}\n"],"mappings":"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"}
+{"version":3,"file":"Validators.cjs","names":["ListOfBuiltInConverters","isArrayOf","EnvaptError","BuiltInConverterTypeCheckers"],"sources":["../../../src/engine/Validators.ts"],"sourcesContent":["// Import the converter modules directly, not via the `./converters` barrel: that barrel pulls in\n// ValueConverter, which imports this Validator, so a barrel import here would cycle.\nimport { isArrayOf } from '../converters/Converters';\nimport { ListOfBuiltInConverters, BuiltInConverterTypeCheckers } from '../converters/ListOfBuiltInConverters';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { ArrayOf, ConverterToken } from '../converters/Converters';\nimport type { EnvFileOptions } from '../infra/Dotenv';\nimport type { StandardSchemaV1 } from '../infra/StandardSchema';\nimport type { BuiltInConverter, ConverterFunction, EnvaptConverter, FileApiMode } from '../types';\n\n// eslint-disable-next-line @typescript-eslint/no-extraneous-class -- cohesive dispatch of stateless type guards, same shape as BuiltInConverters\nexport class Validator {\n    /**\n     * Check if a value is a built-in scalar converter token\n     */\n    static isBuiltInConverter<TFallback>(value: EnvaptConverter<TFallback>): value is BuiltInConverter {\n        if (typeof value === 'string') return ListOfBuiltInConverters.includes(value);\n        return false;\n    }\n\n    /**\n     * Check if a value is an `ArrayOf<...>` token produced by {@link Converters.array}.\n     */\n    static isArrayConverter(value: unknown): value is ArrayOf {\n        return isArrayOf(value);\n    }\n\n    // Structural check: `version === 1` + callable `validate` is the minimum dispatchable\n    // shape per the Standard Schema spec.\n    static isStandardSchema(value: unknown): value is StandardSchemaV1 {\n        if (typeof value !== 'object' || value === null) return false;\n        if (!('~standard' in value)) return false;\n        const slot = value['~standard'];\n        if (typeof slot !== 'object' || slot === null) return false;\n        const props = slot as { version?: unknown; validate?: unknown };\n        return props.version === 1 && typeof props.validate === 'function';\n    }\n\n    static customConvertor<TFallback>(\n        converter: EnvaptConverter<TFallback>\n    ): asserts converter is ConverterFunction<TFallback> {\n        if (typeof converter !== 'function') {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidCustomConverter,\n                `Custom converter must be a function, got ${typeof converter}.`\n            );\n        }\n    }\n\n    /**\n     * Runtime validation that the `ArrayOf<...>` configuration is well-formed.\n     */\n    static arrayConverter(value: unknown): asserts value is ArrayOf {\n        if (!isArrayOf(value)) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidArrayConverterType,\n                'Expected an ArrayOf<...> token produced by Converters.array(...)'\n            );\n        }\n\n        if (typeof value.delimiter !== 'string' || value.delimiter.length === 0) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.MissingDelimiter,\n                `ArrayOf<...> requires a non-empty string delimiter, got ${typeof value.delimiter}`\n            );\n        }\n\n        const elementOf = value.of;\n        const isScalar = typeof elementOf === 'string' && ListOfBuiltInConverters.includes(elementOf);\n        const isCustomFn = typeof elementOf === 'function';\n        if (!isScalar && !isCustomFn) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidArrayConverterType,\n                `ArrayOf<...> element (\"of\") must be a built-in scalar token or a function, got ${typeof elementOf}`\n            );\n        }\n    }\n\n    /**\n     * Validate that a string is a valid built-in scalar converter token\n     */\n    static builtInConverter(value: unknown): asserts value is BuiltInConverter {\n        if (typeof value !== 'string') {\n            throw new EnvaptError(EnvaptErrorCodes.InvalidConverterType, `Expected string, got ${typeof value}`);\n        }\n\n        if (!ListOfBuiltInConverters.includes(value as ConverterToken)) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidBuiltInConverter,\n                `\"${value}\" is not a valid converter type. Valid types are: ${ListOfBuiltInConverters.join(',')}`\n            );\n        }\n    }\n\n    /**\n     * Validate that fallback type matches the converter's return type for built-in converters\n     */\n    static validateBuiltInConverterFallback(converter: BuiltInConverter, fallback: unknown): void {\n        const typeChecker = BuiltInConverterTypeCheckers[converter];\n        if (!typeChecker(fallback)) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.FallbackConverterTypeMismatch,\n                `Fallback type does not match converter \"${converter}\". Expected ${converter} compatible type.`\n            );\n        }\n    }\n\n    /**\n     * Validate that all elements in an array fallback have consistent types\n     */\n    static validateArrayFallbackElementTypes(fallback: unknown[]): void {\n        if (fallback.length === 0) return;\n\n        const firstElementType = typeof fallback[0];\n        const hasInconsistentTypes = fallback.some((element, index) => {\n            if (index === 0) return false;\n            return typeof element !== firstElementType;\n        });\n\n        if (hasInconsistentTypes) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.ArrayFallbackElementTypeMismatch,\n                `All elements in array fallback must have the same type. Found mixed types.`\n            );\n        }\n    }\n\n    /**\n     * Validate that an `ArrayOf<...>` element converter matches the runtime types of its\n     * fallback elements. For `Converters.Time` arrays the element-time-string format is also\n     * checked here.\n     */\n    static validateArrayConverterElementTypeMatch(elementOf: ArrayOf['of'], fallback: unknown[]): void {\n        if (fallback.length === 0) return;\n\n        if (typeof elementOf === 'function') {\n            // Custom element converters can return anything; we can't statically validate the fallback shape.\n            return;\n        }\n\n        const elementToken = elementOf;\n\n        // Time array fallbacks may be number[] OR string[] (TimeFallback[]).\n        if (elementToken === 'time') {\n            const everyNumber = fallback.every((v) => typeof v === 'number');\n            const everyString = fallback.every((v) => typeof v === 'string');\n            if (!everyNumber && !everyString) {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.ArrayFallbackElementTypeMismatch,\n                    'Time array fallback must be all numbers or all time-string entries.'\n                );\n            }\n            return;\n        }\n\n        const typeChecker = BuiltInConverterTypeCheckers[elementToken];\n        const firstElement = fallback[0];\n        if (!typeChecker(firstElement)) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.ArrayFallbackElementTypeMismatch,\n                `Array converter type \"${elementToken}\" does not match fallback element type. Expected ${elementToken} compatible elements.`\n            );\n        }\n    }\n\n    /**\n     * Check if a value is a primitive constructor\n     */\n    static isPrimitiveConstructor(\n        value: unknown\n    ): value is typeof String | typeof Number | typeof Boolean | typeof BigInt | typeof Symbol {\n        return value === String || value === Number || value === Boolean || value === BigInt || value === Symbol;\n    }\n\n    /**\n     * Safely coerce a fallback value using a primitive constructor\n     */\n    static coercePrimitiveFallback<CoercedType>(\n        converter: typeof String | typeof Number | typeof Boolean | typeof BigInt | typeof Symbol,\n        fallback: unknown\n    ): CoercedType {\n        if (this.isCorrectPrimitiveType(converter, fallback)) return fallback as CoercedType;\n        return this.performPrimitiveCoercion<CoercedType>(converter, fallback);\n    }\n\n    private static isCorrectPrimitiveType(\n        converter: typeof String | typeof Number | typeof Boolean | typeof BigInt | typeof Symbol,\n        fallback: unknown\n    ): boolean {\n        if (converter === String && typeof fallback === 'string') return true;\n        if (converter === Number && typeof fallback === 'number') return true;\n        if (converter === Boolean && typeof fallback === 'boolean') return true;\n        if (converter === BigInt && typeof fallback === 'bigint') return true;\n        if (converter === Symbol && typeof fallback === 'symbol') return true;\n        return false;\n    }\n\n    private static performPrimitiveCoercion<CoercedType>(\n        converter: typeof String | typeof Number | typeof Boolean | typeof BigInt | typeof Symbol,\n        fallback: unknown\n    ): CoercedType {\n        try {\n            if (converter === String) return String(fallback) as CoercedType;\n            if (converter === Number) return Number(fallback) as CoercedType;\n            if (converter === Boolean) return Boolean(fallback) as CoercedType;\n            if (converter === BigInt) return BigInt(fallback as string | number | bigint) as CoercedType;\n            /* v8 ignore next -- @preserve */\n            if (converter === Symbol) return Symbol.for(String(fallback)) as CoercedType;\n        } catch (error) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.PrimitiveCoercionFailed,\n                `Failed to coerce fallback value using ${converter.name}: ${(error as Error).message}`\n            );\n        }\n\n        /* v8 ignore next -- @preserve */\n        throw new EnvaptError(\n            EnvaptErrorCodes.PrimitiveCoercionFailed,\n            `Unknown primitive converter: ${converter.name}`\n        );\n    }\n\n    /**\n     * Reject non-boolean inputs to `Envapter.syncProcessEnv` so a truthy typo\n     * (`'true'`, `1`, etc.) does not silently enable the mirror.\n     */\n    static validateSyncProcessEnv(value: unknown): asserts value is boolean {\n        if (typeof value !== 'boolean') {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidUserDefinedConfig,\n                `Envapter.syncProcessEnv must be a boolean, got ${typeof value}.`\n            );\n        }\n    }\n\n    static validateFileApiMode(value: unknown): asserts value is FileApiMode {\n        if (value !== 'warn' && value !== 'throw') {\n            const got = typeof value === 'string' ? `'${value}'` : typeof value;\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidUserDefinedConfig,\n                `Envapter.fileApiMode must be 'warn' or 'throw', got ${got}.`\n            );\n        }\n    }\n\n    /**\n     * Make sure the user hasn't provided prohibited options in their dotenv config\n     */\n    static validateEnvFileOptions(config: object): config is EnvFileOptions {\n        const validKeys = new Set(['encoding', 'override']);\n        const invalidKeys = Object.keys(config).filter((key) => !validKeys.has(key));\n\n        if (invalidKeys.length > 0) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidUserDefinedConfig,\n                `Invalid envFileOptions: ${invalidKeys.join(', ')}. Allowed options: ${Array.from(validKeys).join(', ')}. For debug output, use Envapter.debug or the ENVAPT_DEBUG env var.`\n            );\n        }\n\n        return true;\n    }\n\n    // Existence is probed through the caller-supplied `fileExists` (backed by the bound source) so\n    // this stays free of `node:fs`.\n    static validateEnvFilesExist(paths: string[], fileExists: (path: string) => boolean): void {\n        const missing = paths.filter((p) => !fileExists(p));\n\n        if (missing.length > 0) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.EnvFilesNotFound,\n                `Environment file not found at path: ${missing.join(', ')}`\n            );\n        }\n    }\n}\n"],"mappings":"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"}