envapt 8.1.0 → 8.1.1

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

@@ -1 +1 @@
-{"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\nimport type { EnvKeyInput } from '../types';\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     * @see {@link https://envapt.materwelon.dev/docs/templates#the-resolve-tagged-template}\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 after template\n     * resolution. Throws `MissingEnvValue` listing every missing key. A whitespace-only value\n     * counts as missing only under strict mode.\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    /**\n     * Check whether `key` has a value, with the same missing semantics as `getRequired`.\n     * Under strict mode an unresolvable template in an ordered key list ends the scan early\n     * and counts as absent. Returns `true` exactly when a required read of the same key\n     * finds a value.\n     *\n     * @example\n     * ```ts\n     * if (!Envapter.has('DATABASE_URL')) throw new MyStartupError('DATABASE_URL');\n     * ```\n     * @see {@link https://envapt.materwelon.dev/docs/envapter#fail-fast-on-missing-values}\n     */\n    static has(key: EnvKeyInput): boolean {\n        try {\n            return resolveRequired(resolveKeyInput(key), templateResolver).value !== undefined;\n        } catch (error) {\n            // under strict an unresolvable template throws MissingEnvValue, and that read counts as absent\n            if (error instanceof EnvaptError && error.code === EnvaptErrorCodes.MissingEnvValue) return false;\n            throw error;\n        }\n    }\n\n    /**\n     * @see {@link Envapter.has}\n     */\n    has(key: EnvKeyInput): boolean {\n        return Envapter.has(key);\n    }\n}\n"],"mappings":"wJAgCA,IAAa,EAAb,MAAa,UAAiBA,EAAAA,eAAgB,CAiB1C,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,CAeA,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,CAcA,OAAO,IAAI,EAA2B,CAClC,GAAI,CACA,OAAOC,EAAAA,gBAAgBC,EAAAA,gBAAgB,CAAG,EAAGC,EAAAA,gBAAgB,CAAC,CAAC,QAAU,IAAA,EAC7E,OAAS,EAAO,CAEZ,GAAI,aAAiBH,EAAAA,aAAe,EAAM,OAAA,IAA2C,MAAO,GAC5F,MAAM,CACV,CACJ,CAKA,IAAI,EAA2B,CAC3B,OAAO,EAAS,IAAI,CAAG,CAC3B,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\nimport type { EnvKeyInput } from '../types';\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     * @see {@link https://envapt.materwelon.dev/docs/templates#the-resolve-tagged-template}\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 after template\n     * resolution. Throws `MissingEnvValue` listing every missing key. A whitespace-only value\n     * counts as missing only under strict mode.\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    /**\n     * Check whether `key` has a value, with the same missing semantics as `getRequired`.\n     * Under strict mode an unresolvable template in an ordered key list ends the scan early\n     * and counts as absent. Returns `true` exactly when a required read of the same key\n     * finds a value.\n     *\n     * @example\n     * ```ts\n     * if (!Envapter.has('DATABASE_URL')) throw new MyStartupError('DATABASE_URL');\n     * ```\n     * @see {@link https://envapt.materwelon.dev/docs/envapter#fail-fast-on-missing-values}\n     */\n    static has(key: EnvKeyInput): boolean {\n        try {\n            return resolveRequired(resolveKeyInput(key), templateResolver).value !== undefined;\n        } catch (error) {\n            // under strict an unresolvable template throws MissingEnvValue, and that read counts as absent\n            if (error instanceof EnvaptError && error.code === EnvaptErrorCodes.MissingEnvValue) return false;\n            throw error;\n        }\n    }\n\n    /**\n     * @see {@link Envapter.has}\n     */\n    has(key: EnvKeyInput): boolean {\n        return Envapter.has(key);\n    }\n}\n"],"mappings":"oJAgCA,IAAa,EAAb,MAAa,UAAiBA,EAAAA,eAAgB,CAiB1C,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,CAeA,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,CAcA,OAAO,IAAI,EAA2B,CAClC,GAAI,CACA,OAAOC,EAAAA,gBAAgBC,EAAAA,gBAAgB,CAAG,EAAGC,EAAAA,gBAAgB,CAAC,CAAC,QAAU,IAAA,EAC7E,OAAS,EAAO,CAEZ,GAAI,aAAiBH,EAAAA,aAAe,EAAM,OAAA,IAA2C,MAAO,GAC5F,MAAM,CACV,CACJ,CAKA,IAAI,EAA2B,CAC3B,OAAO,EAAS,IAAI,CAAG,CAC3B,CACJ"}

package/dist/node/engine/Envapter.mjs

@@ -1,2 +1,2 @@
-import{EnvaptError as e}from"../infra/Error.mjs";import"../core/Environment.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)}static has(r){try{return i(t(r),n).value!==void 0}catch(t){if(t instanceof e&&t.code===305)return!1;throw t}}has(e){return a.has(e)}};export{a as Envapter};
+import{EnvaptError as e}from"../infra/Error.mjs";import{Environment as t}from"../core/Environment.mjs";import{resolveKeyInput as n,templateResolver as r}from"../core/engine.mjs";import{AdvancedMethods as i,resolveRequired as a}from"../core/AdvancedMethods.mjs";var o=class t extends i{static resolve(n,...r){let i=t.strict;return n.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,...n){return t.resolve(e,...n)}static require(...t){let i=t.filter(e=>a(n(e),r).value===void 0);if(i.length>0)throw new e(305,`Missing required environment variables: ${i.join(`, `)}.`)}require(...e){t.require(...e)}static has(t){try{return a(n(t),r).value!==void 0}catch(t){if(t instanceof e&&t.code===305)return!1;throw t}}has(e){return t.has(e)}};export{o as Envapter,t as Environment};
 //# 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 { resolveRequired } from '../core/AdvancedMethods';\nimport { resolveKeyInput, templateResolver } from '../core/engine';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { EnvKeyInput } from '../types';\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     * @see {@link https://envapt.materwelon.dev/docs/templates#the-resolve-tagged-template}\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 after template\n     * resolution. Throws `MissingEnvValue` listing every missing key. A whitespace-only value\n     * counts as missing only under strict mode.\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    /**\n     * Check whether `key` has a value, with the same missing semantics as `getRequired`.\n     * Under strict mode an unresolvable template in an ordered key list ends the scan early\n     * and counts as absent. Returns `true` exactly when a required read of the same key\n     * finds a value.\n     *\n     * @example\n     * ```ts\n     * if (!Envapter.has('DATABASE_URL')) throw new MyStartupError('DATABASE_URL');\n     * ```\n     * @see {@link https://envapt.materwelon.dev/docs/envapter#fail-fast-on-missing-values}\n     */\n    static has(key: EnvKeyInput): boolean {\n        try {\n            return resolveRequired(resolveKeyInput(key), templateResolver).value !== undefined;\n        } catch (error) {\n            // under strict an unresolvable template throws MissingEnvValue, and that read counts as absent\n            if (error instanceof EnvaptError && error.code === EnvaptErrorCodes.MissingEnvValue) return false;\n            throw error;\n        }\n    }\n\n    /**\n     * @see {@link Envapter.has}\n     */\n    has(key: EnvKeyInput): boolean {\n        return Envapter.has(key);\n    }\n}\n"],"mappings":"+OAgCA,IAAa,EAAb,MAAa,UAAiB,CAAgB,CAiB1C,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,CAeA,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,CAcA,OAAO,IAAI,EAA2B,CAClC,GAAI,CACA,OAAO,EAAgB,EAAgB,CAAG,EAAG,CAAgB,CAAC,CAAC,QAAU,IAAA,EAC7E,OAAS,EAAO,CAEZ,GAAI,aAAiB,GAAe,EAAM,OAAA,IAA2C,MAAO,GAC5F,MAAM,CACV,CACJ,CAKA,IAAI,EAA2B,CAC3B,OAAO,EAAS,IAAI,CAAG,CAC3B,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\nimport type { EnvKeyInput } from '../types';\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     * @see {@link https://envapt.materwelon.dev/docs/templates#the-resolve-tagged-template}\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 after template\n     * resolution. Throws `MissingEnvValue` listing every missing key. A whitespace-only value\n     * counts as missing only under strict mode.\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    /**\n     * Check whether `key` has a value, with the same missing semantics as `getRequired`.\n     * Under strict mode an unresolvable template in an ordered key list ends the scan early\n     * and counts as absent. Returns `true` exactly when a required read of the same key\n     * finds a value.\n     *\n     * @example\n     * ```ts\n     * if (!Envapter.has('DATABASE_URL')) throw new MyStartupError('DATABASE_URL');\n     * ```\n     * @see {@link https://envapt.materwelon.dev/docs/envapter#fail-fast-on-missing-values}\n     */\n    static has(key: EnvKeyInput): boolean {\n        try {\n            return resolveRequired(resolveKeyInput(key), templateResolver).value !== undefined;\n        } catch (error) {\n            // under strict an unresolvable template throws MissingEnvValue, and that read counts as absent\n            if (error instanceof EnvaptError && error.code === EnvaptErrorCodes.MissingEnvValue) return false;\n            throw error;\n        }\n    }\n\n    /**\n     * @see {@link Envapter.has}\n     */\n    has(key: EnvKeyInput): boolean {\n        return Envapter.has(key);\n    }\n}\n"],"mappings":"qQAgCA,IAAa,EAAb,MAAa,UAAiB,CAAgB,CAiB1C,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,CAeA,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,CAcA,OAAO,IAAI,EAA2B,CAClC,GAAI,CACA,OAAO,EAAgB,EAAgB,CAAG,EAAG,CAAgB,CAAC,CAAC,QAAU,IAAA,EAC7E,OAAS,EAAO,CAEZ,GAAI,aAAiB,GAAe,EAAM,OAAA,IAA2C,MAAO,GAC5F,MAAM,CACV,CACJ,CAKA,IAAI,EAA2B,CAC3B,OAAO,EAAS,IAAI,CAAG,CAC3B,CACJ"}

package/dist/node/engine/Validators.cjs

@@ -1,2 +1,2 @@
-const e=require("../infra/Error.cjs"),t=require("../converters/Converters.cjs"),n=require("../converters/ListOfBuiltInConverters.cjs");var r=class{static isBuiltInConverter(e){return typeof e==`string`?n.ListOfBuiltInConverters.includes(e):!1}static isArrayConverter(e){return t.isArrayOf(e)}static isStandardSchema(e){if(typeof e!=`object`||!e||!(`~standard`in e))return!1;let t=e[`~standard`];if(typeof t!=`object`||!t)return!1;let n=t;return n.version===1&&typeof n.validate==`function`}static customConvertor(t){if(typeof t!=`function`)throw new e.EnvaptError(203,`Custom converter must be a function, got ${typeof t}.`)}static arrayConverter(r){if(!t.isArrayOf(r))throw new e.EnvaptError(201,`Expected an ArrayOf<...> token produced by Converters.array(...)`);if(typeof r.delimiter!=`string`||r.delimiter.length===0)throw new e.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 e.EnvaptError(201,`ArrayOf<...> element ("of") must be a built-in scalar token or a function, got ${typeof i}`)}static builtInConverter(t){if(typeof t!=`string`)throw new e.EnvaptError(204,`Expected string, got ${typeof t}`);if(!n.ListOfBuiltInConverters.includes(t))throw new e.EnvaptError(202,`"${t}" is not a valid converter type. Valid types are: ${n.ListOfBuiltInConverters.join(`,`)}`)}static validateBuiltInConverterFallback(t,r){let i=n.BuiltInConverterTypeCheckers[t];if(!i(r))throw new e.EnvaptError(104,`Fallback type does not match converter "${t}". Expected ${t} compatible type.`)}static validateArrayFallbackElementTypes(t){if(t.length===0)return;let n=typeof t[0];if(t.some((e,t)=>t===0?!1:typeof e!==n))throw new e.EnvaptError(103,`All elements in array fallback must have the same type. Found mixed types.`)}static validateArrayConverterElementTypeMatch(t,r){if(r.length===0||typeof t==`function`)return;let i=t;if(i===`time`){let t=r.every(e=>typeof e==`number`),n=r.every(e=>typeof e==`string`);if(!t&&!n)throw new e.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 e.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(t,n){try{if(t===String)return String(n);if(t===Number)return Number(n);if(t===Boolean)return!!n;if(t===BigInt)return BigInt(n);if(t===Symbol)return Symbol.for(String(n))}catch(n){throw new e.EnvaptError(205,`Failed to coerce fallback value using ${t.name}: ${n.message}`)}throw new e.EnvaptError(205,`Unknown primitive converter: ${t.name}`)}static validateSyncProcessEnv(t){if(typeof t!=`boolean`)throw new e.EnvaptError(302,`Envapter.syncProcessEnv must be a boolean, got ${typeof t}.`)}static validateFileApiMode(t){if(t!==`warn`&&t!==`throw`){let n=typeof t==`string`?`'${t}'`:typeof t;throw new e.EnvaptError(302,`Envapter.fileApiMode must be 'warn' or 'throw', got ${n}.`)}}static validateEnvFileOptions(t){let n=new Set([`encoding`,`override`]),r=Object.keys(t).filter(e=>!n.has(e));if(r.length>0)throw new e.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(t,n){let r=t.filter(e=>!n(e));if(r.length>0)throw new e.EnvaptError(303,`Environment file not found at path: ${r.join(`, `)}`)}};exports.Validator=r;
+const e=require("../infra/Error.cjs"),t=require("../converters/Converters.cjs"),n=require("../converters/ListOfBuiltInConverters.cjs");var r=class{static isBuiltInConverter(e){return typeof e==`string`&&n.ListOfBuiltInConverters.includes(e)}static isArrayConverter(e){return t.isArrayOf(e)}static isStandardSchema(e){if(typeof e!=`object`||!e||!(`~standard`in e))return!1;let t=e[`~standard`];if(typeof t!=`object`||!t)return!1;let n=t;return n.version===1&&typeof n.validate==`function`}static customConvertor(t){if(typeof t!=`function`)throw new e.EnvaptError(203,`Custom converter must be a function, got ${typeof t}.`)}static arrayConverter(r){if(!t.isArrayOf(r))throw new e.EnvaptError(201,`Expected an ArrayOf<...> token produced by Converters.array(...)`);if(typeof r.delimiter!=`string`||r.delimiter.length===0)throw new e.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 e.EnvaptError(201,`ArrayOf<...> element ("of") must be a built-in scalar token or a function, got ${typeof i}`)}static builtInConverter(t){if(typeof t!=`string`)throw new e.EnvaptError(204,`Expected string, got ${typeof t}`);if(!n.ListOfBuiltInConverters.includes(t))throw new e.EnvaptError(202,`"${t}" is not a valid converter type. Valid types are: ${n.ListOfBuiltInConverters.join(`,`)}`)}static validateBuiltInConverterFallback(t,r){let i=n.BuiltInConverterTypeCheckers[t];if(!i(r))throw new e.EnvaptError(104,`Fallback type does not match converter "${t}". Expected ${t} compatible type.`)}static validateArrayFallbackElementTypes(t){if(t.length===0)return;let n=typeof t[0];if(t.some((e,t)=>t!==0&&typeof e!==n))throw new e.EnvaptError(103,`All elements in array fallback must have the same type. Found mixed types.`)}static validateArrayConverterElementTypeMatch(t,r){if(r.length===0||typeof t==`function`)return;let i=t;if(i===`time`){let t=r.every(e=>typeof e==`number`),n=r.every(e=>typeof e==`string`);if(!t&&!n)throw new e.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 e.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(t,n){try{if(t===String)return String(n);if(t===Number)return Number(n);if(t===Boolean)return!!n;if(t===BigInt)return BigInt(n);if(t===Symbol)return Symbol.for(String(n))}catch(n){throw new e.EnvaptError(205,`Failed to coerce fallback value using ${t.name}: ${n.message}`)}throw new e.EnvaptError(205,`Unknown primitive converter: ${t.name}`)}static validateSyncProcessEnv(t){if(typeof t!=`boolean`)throw new e.EnvaptError(302,`Envapter.syncProcessEnv must be a boolean, got ${typeof t}.`)}static validateFileApiMode(t){if(t!==`warn`&&t!==`throw`){let n=typeof t==`string`?`'${t}'`:typeof t;throw new e.EnvaptError(302,`Envapter.fileApiMode must be 'warn' or 'throw', got ${n}.`)}}static validateEnvFileOptions(t){let n=new Set([`encoding`,`override`]),r=Object.keys(t).filter(e=>!n.has(e));if(r.length>0)throw new e.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(t,n){let r=t.filter(e=>!n(e));if(r.length>0)throw new e.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, 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":"uIAYA,IAAa,EAAb,KAAuB,CAInB,OAAO,mBAA8B,EAA8D,CAE/F,OADI,OAAO,GAAU,SAAiBA,EAAAA,wBAAwB,SAAS,CAAK,EACrE,EACX,CAKA,OAAO,iBAAiB,EAAkC,CACtD,OAAOC,EAAAA,UAAU,CAAK,CAC1B,CAIA,OAAO,iBAAiB,EAA2C,CAE/D,GADI,OAAO,GAAU,WAAY,GAC7B,EAAE,cAAe,GAAQ,MAAO,GACpC,IAAM,EAAO,EAAM,aACnB,GAAI,OAAO,GAAS,WAAY,EAAe,MAAO,GACtD,IAAM,EAAQ,EACd,OAAO,EAAM,UAAY,GAAK,OAAO,EAAM,UAAa,UAC5D,CAEA,OAAO,gBACH,EACiD,CACjD,GAAI,OAAO,GAAc,WACrB,MAAM,IAAIC,EAAAA,YAAAA,IAEN,4CAA4C,OAAO,EAAU,EACjE,CAER,CAKA,OAAO,eAAe,EAA0C,CAC5D,GAAI,CAACD,EAAAA,UAAU,CAAK,EAChB,MAAM,IAAIC,EAAAA,YAAAA,IAEN,kEACJ,EAGJ,GAAI,OAAO,EAAM,WAAc,UAAY,EAAM,UAAU,SAAW,EAClE,MAAM,IAAIA,EAAAA,YAAAA,IAEN,2DAA2D,OAAO,EAAM,WAC5E,EAGJ,IAAM,EAAY,EAAM,GAGxB,GAAI,EAFa,OAAO,GAAc,UAAYF,EAAAA,wBAAwB,SAAS,CAAS,IACzE,OAAO,GAAc,WAEpC,MAAM,IAAIE,EAAAA,YAAAA,IAEN,kFAAkF,OAAO,GAC7F,CAER,CAKA,OAAO,iBAAiB,EAAmD,CACvE,GAAI,OAAO,GAAU,SACjB,MAAM,IAAIA,EAAAA,YAAAA,IAAmD,wBAAwB,OAAO,GAAO,EAGvG,GAAI,CAACF,EAAAA,wBAAwB,SAAS,CAAuB,EACzD,MAAM,IAAIE,EAAAA,YAAAA,IAEN,IAAI,EAAM,oDAAoDF,EAAAA,wBAAwB,KAAK,GAAG,GAClG,CAER,CAKA,OAAO,iCAAiC,EAA6B,EAAyB,CAC1F,IAAM,EAAcG,EAAAA,6BAA6B,GACjD,GAAI,CAAC,EAAY,CAAQ,EACrB,MAAM,IAAID,EAAAA,YAAAA,IAEN,2CAA2C,EAAU,cAAc,EAAU,kBACjF,CAER,CAKA,OAAO,kCAAkC,EAA2B,CAChE,GAAI,EAAS,SAAW,EAAG,OAE3B,IAAM,EAAmB,OAAO,EAAS,GAMzC,GAL6B,EAAS,MAAM,EAAS,IAC7C,IAAU,EAAU,GACjB,OAAO,IAAY,CAGP,EACnB,MAAM,IAAIA,EAAAA,YAAAA,IAEN,4EACJ,CAER,CAOA,OAAO,uCAAuC,EAA0B,EAA2B,CAG/F,GAFI,EAAS,SAAW,GAEpB,OAAO,GAAc,WAErB,OAGJ,IAAM,EAAe,EAGrB,GAAI,IAAiB,OAAQ,CACzB,IAAM,EAAc,EAAS,MAAO,GAAM,OAAO,GAAM,QAAQ,EACzD,EAAc,EAAS,MAAO,GAAM,OAAO,GAAM,QAAQ,EAC/D,GAAI,CAAC,GAAe,CAAC,EACjB,MAAM,IAAIA,EAAAA,YAAAA,IAEN,qEACJ,EAEJ,MACJ,CAEA,IAAM,EAAcC,EAAAA,6BAA6B,GAC3C,EAAe,EAAS,GAC9B,GAAI,CAAC,EAAY,CAAY,EACzB,MAAM,IAAID,EAAAA,YAAAA,IAEN,yBAAyB,EAAa,mDAAmD,EAAa,sBAC1G,CAER,CAKA,OAAO,uBACH,EACuF,CACvF,OAAO,IAAU,QAAU,IAAU,QAAU,IAAU,SAAW,IAAU,QAAU,IAAU,MACtG,CAKA,OAAO,wBACH,EACA,EACW,CAEX,OADI,KAAK,uBAAuB,EAAW,CAAQ,EAAU,EACtD,KAAK,yBAAsC,EAAW,CAAQ,CACzE,CAEA,OAAe,uBACX,EACA,EACO,CAMP,OALI,IAAc,QAAU,OAAO,GAAa,UAC5C,IAAc,QAAU,OAAO,GAAa,UAC5C,IAAc,SAAW,OAAO,GAAa,WAC7C,IAAc,QAAU,OAAO,GAAa,UAC5C,IAAc,QAAU,OAAO,GAAa,QAEpD,CAEA,OAAe,yBACX,EACA,EACW,CACX,GAAI,CACA,GAAI,IAAc,OAAQ,OAAO,OAAO,CAAQ,EAChD,GAAI,IAAc,OAAQ,OAAO,OAAO,CAAQ,EAChD,GAAI,IAAc,QAAS,MAAO,EAAQ,EAC1C,GAAI,IAAc,OAAQ,OAAO,OAAO,CAAoC,EAE5E,GAAI,IAAc,OAAQ,OAAO,OAAO,IAAI,OAAO,CAAQ,CAAC,CAChE,OAAS,EAAO,CACZ,MAAM,IAAIA,EAAAA,YAAAA,IAEN,yCAAyC,EAAU,KAAK,IAAK,EAAgB,SACjF,CACJ,CAGA,MAAM,IAAIA,EAAAA,YAAAA,IAEN,gCAAgC,EAAU,MAC9C,CACJ,CAMA,OAAO,uBAAuB,EAA0C,CACpE,GAAI,OAAO,GAAU,UACjB,MAAM,IAAIA,EAAAA,YAAAA,IAEN,kDAAkD,OAAO,EAAM,EACnE,CAER,CAEA,OAAO,oBAAoB,EAA8C,CACrE,GAAI,IAAU,QAAU,IAAU,QAAS,CACvC,IAAM,EAAM,OAAO,GAAU,SAAW,IAAI,EAAM,GAAK,OAAO,EAC9D,MAAM,IAAIA,EAAAA,YAAAA,IAEN,uDAAuD,EAAI,EAC/D,CACJ,CACJ,CAKA,OAAO,uBAAuB,EAA0C,CACpE,IAAM,EAAY,IAAI,IAAI,CAAC,WAAY,UAAU,CAAC,EAC5C,EAAc,OAAO,KAAK,CAAM,CAAC,CAAC,OAAQ,GAAQ,CAAC,EAAU,IAAI,CAAG,CAAC,EAE3E,GAAI,EAAY,OAAS,EACrB,MAAM,IAAIA,EAAAA,YAAAA,IAEN,2BAA2B,EAAY,KAAK,IAAI,EAAE,qBAAqB,MAAM,KAAK,CAAS,CAAC,CAAC,KAAK,IAAI,EAAE,oEAC5G,EAGJ,MAAO,EACX,CAIA,OAAO,sBAAsB,EAAiB,EAA6C,CACvF,IAAM,EAAU,EAAM,OAAQ,GAAM,CAAC,EAAW,CAAC,CAAC,EAElD,GAAI,EAAQ,OAAS,EACjB,MAAM,IAAIA,EAAAA,YAAAA,IAEN,uCAAuC,EAAQ,KAAK,IAAI,GAC5D,CAER,CACJ"}
+{"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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"}

package/dist/node/engine/Validators.mjs

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

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

@@ -1 +1 @@
-{"version":3,"file":"Validators.mjs","names":[],"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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"}
+{"version":3,"file":"Validators.mjs","names":[],"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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"}

package/dist/node/infra/Dotenv.cjs

@@ -1,3 +1,3 @@
 const e=require("./Debug.cjs"),t=/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/u;function n(e){let t=new Map,n=e.split(/\r?\n/u);for(let e=0;e<n.length;e++){let i=r(n,e);e=i.endLine,i.entry&&t.set(i.entry.key,i.entry.value)}return t}function r(e,n){let r=e[n]??``,o=r.trim();if(o===``||o.startsWith(`#`))return{entry:void 0,endLine:n};let s=r.match(t);if(!s)return{entry:void 0,endLine:n};let c=s[1],l=(s[2]??``).replace(/^\s+/u,``),u=l[0];if(u===`"`||u===`'`||u==="`"){let t=i(l,e,n,u);return{entry:{key:c,value:t.value},endLine:t.endLine}}return{entry:{key:c,value:a(l)},endLine:n}}function i(e,t,n,r){let i=e,a=n,o=s(i,r);for(;o<0&&a<t.length-1;)a++,i+=`\n${t[a]??``}`,o=s(i,r);let l=o>0?i.slice(1,o):i.slice(1);return{value:r===`"`?c(l):l,endLine:a}}function a(e){let t=o(e);return(t===-1?e:e.slice(0,t)).trimEnd()}function o(e){for(let t=0;t<e.length;t++)if(e[t]===`#`&&(t===0||/\s/u.test(e[t-1])))return t;return-1}function s(e,t){for(let n=e.length-1;n>0;n--)if(e[n]===t){if(t===`"`){let t=0,r=n-1;for(;r>=0&&e[r]===`\\`;)t++,r--;if(t%2==1)continue}return n}return-1}function c(e){let t=``;for(let n=0;n<e.length;n++){let r=e[n];if(r!==`\\`||n===e.length-1){t+=r;continue}let i=e[n+1];switch(n++,i){case`n`:t+=`
-`;break;case`r`:t+=`\r`;break;case`t`:t+=`	`;break;case`\\`:t+=`\\`;break;case`"`:t+=`"`;break;default:t+=`\\${i??``}`}}return t}function l(t){let r=Array.isArray(t.path)?t.path:[t.path],i=t.encoding??`utf8`,a=t.override??!1,o=new Set;for(let s of r){let r=t.readFile(s,i);if(r===void 0){e.debugWarn(`could not read ${s}`);continue}let c=n(r);e.debugVerbose(`loaded ${s}: ${c.size} ${c.size===1?`key`:`keys`}`);for(let[n,r]of c)(!Object.prototype.hasOwnProperty.call(t.processEnv,n)||a)&&(t.processEnv[n]=r,o.add(n),e.debugVerbose(`${s} -> ${n}`))}return o}exports.loadDotenv=l;
+`;break;case`r`:t+=`\r`;break;case`t`:t+=`	`;break;case`\\`:t+=`\\`;break;case`"`:t+=`"`;break;default:t+=`\\${i??``}`}}return t}function l(t){let r=Array.isArray(t.path)?t.path:[t.path],i=t.encoding??`utf8`,a=t.override??!1,o=new Set;for(let s of r){let r=t.readFile(s,i);if(r===void 0){e.debugWarn(`could not read ${s}`);continue}let c=n(r);e.debugVerbose(`loaded ${s}: ${c.size} ${c.size===1?`key`:`keys`}`);for(let[n,r]of c)(!Object.prototype.hasOwnProperty.call(t.processEnv,n)||a)&&(t.processEnv[n]=r,o.add(n),e.debugVerbose(`${s} -> ${n}`))}return o}exports.loadDotenv=l,exports.parseDotenv=n;
 //# sourceMappingURL=Dotenv.cjs.map

package/dist/node/infra/Dotenv.mjs

@@ -1,3 +1,3 @@
 import{debugVerbose as e,debugWarn as t}from"./Debug.mjs";const n=/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/u;function r(e){let t=new Map,n=e.split(/\r?\n/u);for(let e=0;e<n.length;e++){let r=i(n,e);e=r.endLine,r.entry&&t.set(r.entry.key,r.entry.value)}return t}function i(e,t){let r=e[t]??``,i=r.trim();if(i===``||i.startsWith(`#`))return{entry:void 0,endLine:t};let s=r.match(n);if(!s)return{entry:void 0,endLine:t};let c=s[1],l=(s[2]??``).replace(/^\s+/u,``),u=l[0];if(u===`"`||u===`'`||u==="`"){let n=a(l,e,t,u);return{entry:{key:c,value:n.value},endLine:n.endLine}}return{entry:{key:c,value:o(l)},endLine:t}}function a(e,t,n,r){let i=e,a=n,o=c(i,r);for(;o<0&&a<t.length-1;)a++,i+=`\n${t[a]??``}`,o=c(i,r);let s=o>0?i.slice(1,o):i.slice(1);return{value:r===`"`?l(s):s,endLine:a}}function o(e){let t=s(e);return(t===-1?e:e.slice(0,t)).trimEnd()}function s(e){for(let t=0;t<e.length;t++)if(e[t]===`#`&&(t===0||/\s/u.test(e[t-1])))return t;return-1}function c(e,t){for(let n=e.length-1;n>0;n--)if(e[n]===t){if(t===`"`){let t=0,r=n-1;for(;r>=0&&e[r]===`\\`;)t++,r--;if(t%2==1)continue}return n}return-1}function l(e){let t=``;for(let n=0;n<e.length;n++){let r=e[n];if(r!==`\\`||n===e.length-1){t+=r;continue}let i=e[n+1];switch(n++,i){case`n`:t+=`
-`;break;case`r`:t+=`\r`;break;case`t`:t+=`	`;break;case`\\`:t+=`\\`;break;case`"`:t+=`"`;break;default:t+=`\\${i??``}`}}return t}function u(n){let i=Array.isArray(n.path)?n.path:[n.path],a=n.encoding??`utf8`,o=n.override??!1,s=new Set;for(let c of i){let i=n.readFile(c,a);if(i===void 0){t(`could not read ${c}`);continue}let l=r(i);e(`loaded ${c}: ${l.size} ${l.size===1?`key`:`keys`}`);for(let[t,r]of l)(!Object.prototype.hasOwnProperty.call(n.processEnv,t)||o)&&(n.processEnv[t]=r,s.add(t),e(`${c} -> ${t}`))}return s}export{u as loadDotenv};
+`;break;case`r`:t+=`\r`;break;case`t`:t+=`	`;break;case`\\`:t+=`\\`;break;case`"`:t+=`"`;break;default:t+=`\\${i??``}`}}return t}function u(n){let i=Array.isArray(n.path)?n.path:[n.path],a=n.encoding??`utf8`,o=n.override??!1,s=new Set;for(let c of i){let i=n.readFile(c,a);if(i===void 0){t(`could not read ${c}`);continue}let l=r(i);e(`loaded ${c}: ${l.size} ${l.size===1?`key`:`keys`}`);for(let[t,r]of l)(!Object.prototype.hasOwnProperty.call(n.processEnv,t)||o)&&(n.processEnv[t]=r,s.add(t),e(`${c} -> ${t}`))}return s}export{u as loadDotenv,r as parseDotenv};
 //# sourceMappingURL=Dotenv.mjs.map

package/dist/node/sources/FileSource.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"FileSource.cjs","names":["process","fs"],"sources":["../../../src/sources/FileSource.ts"],"sourcesContent":["import fs from 'node:fs';\nimport { dirname, isAbsolute, join, resolve } from 'node:path';\nimport process from 'node:process';\nimport { fileURLToPath } from 'node:url';\n\nimport type { FileCapableSource } from '../types';\n\n/**\n * Default environment source on Node, Bun, and Deno: a snapshot of `process.env`. Its\n * `supportsFiles` is `true`, so the engine also layers the `.env` cascade on top, resolves\n * `baseDir`, and can mirror loaded keys back to `process.env`.\n * @public\n * @see {@link https://envapt.materwelon.dev/docs/sources#the-providers}\n */\nexport class FileSource implements FileCapableSource {\n    /** Always `true`. The engine layers the `.env` cascade and `baseDir` on top of `process.env`. */\n    readonly supportsFiles = true;\n\n    /** Returns a snapshot clone of `process.env` as plain strings. */\n    readVars(): Record<string, string> {\n        // Clone so the loader and downstream reads never mutate process.env.\n        return { ...(process.env as Record<string, string>) };\n    }\n\n    /** Reads a file with `fs.readFileSync`, or `undefined` when it is missing or unreadable. */\n    readFile(path: string, encoding: string): string | undefined {\n        try {\n            // justified: our public encoding type is `string`; fs needs the BufferEncoding subset.\n            return fs.readFileSync(path, encoding as BufferEncoding);\n        } catch {\n            return undefined;\n        }\n    }\n\n    /**\n     * Resolves a directory path or a module / `file:` URL to an absolute directory. A `file:` URL\n     * resolves to its containing directory, and a plain path (`import.meta.dirname`, `__dirname`) is\n     * taken as the directory itself.\n     */\n    normalizeBaseDir(value: string | URL): string {\n        if (value instanceof URL) return dirname(fileURLToPath(value));\n        if (value.startsWith('file:')) return dirname(fileURLToPath(value));\n        return resolve(value);\n    }\n\n    /** Joins a relative `.env` path onto `baseDir`. Absolute paths pass through unchanged. */\n    resolvePath(baseDir: string, candidate: string): string {\n        if (isAbsolute(candidate)) return candidate;\n        return join(baseDir, candidate);\n    }\n\n    /** Writes each key to `process.env`, backing `Envapter.syncProcessEnv`. */\n    writeVars(vars: Record<string, string>): void {\n        for (const [key, value] of Object.entries(vars)) {\n            process.env[key] = value;\n        }\n    }\n}\n"],"mappings":"+LAcA,IAAa,EAAb,KAAqD,CAEjD,cAAyB,GAGzB,UAAmC,CAE/B,MAAO,CAAE,GAAIA,EAAAA,QAAQ,GAA+B,CACxD,CAGA,SAAS,EAAc,EAAsC,CACzD,GAAI,CAEA,OAAOC,EAAAA,QAAG,aAAa,EAAM,CAA0B,CAC3D,MAAQ,CACJ,MACJ,CACJ,CAOA,iBAAiB,EAA6B,CAG1C,OAFI,aAAiB,KACjB,EAAM,WAAW,OAAO,GAAG,EAAA,EAAA,QAAA,EAAA,EAAA,EAAA,cAAA,CAA6B,CAAK,CAAC,GAClE,EAAA,EAAA,QAAA,CAAe,CAAK,CACxB,CAGA,YAAY,EAAiB,EAA2B,CAEpD,OADA,EAAA,EAAA,WAAA,CAAe,CAAS,EAAU,GAClC,EAAA,EAAA,KAAA,CAAY,EAAS,CAAS,CAClC,CAGA,UAAU,EAAoC,CAC1C,IAAK,GAAM,CAAC,EAAK,KAAU,OAAO,QAAQ,CAAI,EAC1C,EAAA,QAAQ,IAAI,GAAO,CAE3B,CACJ"}
+{"version":3,"file":"FileSource.cjs","names":["process","fs","dirname","fileURLToPath","resolve","isAbsolute","join"],"sources":["../../../src/sources/FileSource.ts"],"sourcesContent":["import fs from 'node:fs';\nimport { dirname, isAbsolute, join, resolve } from 'node:path';\nimport process from 'node:process';\nimport { fileURLToPath } from 'node:url';\n\nimport type { FileCapableSource } from '../types';\n\n/**\n * Default environment source on Node, Bun, and Deno: a snapshot of `process.env`. Its\n * `supportsFiles` is `true`, so the engine also layers the `.env` cascade on top, resolves\n * `baseDir`, and can mirror loaded keys back to `process.env`.\n * @public\n * @see {@link https://envapt.materwelon.dev/docs/sources#the-providers}\n */\nexport class FileSource implements FileCapableSource {\n    /** Always `true`. The engine layers the `.env` cascade and `baseDir` on top of `process.env`. */\n    readonly supportsFiles = true;\n\n    /** Returns a snapshot clone of `process.env` as plain strings. */\n    readVars(): Record<string, string> {\n        // Clone so the loader and downstream reads never mutate process.env.\n        return { ...(process.env as Record<string, string>) };\n    }\n\n    /** Reads a file with `fs.readFileSync`, or `undefined` when it is missing or unreadable. */\n    readFile(path: string, encoding: string): string | undefined {\n        try {\n            // justified: our public encoding type is `string`; fs needs the BufferEncoding subset.\n            return fs.readFileSync(path, encoding as BufferEncoding);\n        } catch {\n            return undefined;\n        }\n    }\n\n    /**\n     * Resolves a directory path or a module / `file:` URL to an absolute directory. A `file:` URL\n     * resolves to its containing directory, and a plain path (`import.meta.dirname`, `__dirname`) is\n     * taken as the directory itself.\n     */\n    normalizeBaseDir(value: string | URL): string {\n        if (value instanceof URL) return dirname(fileURLToPath(value));\n        if (value.startsWith('file:')) return dirname(fileURLToPath(value));\n        return resolve(value);\n    }\n\n    /** Joins a relative `.env` path onto `baseDir`. Absolute paths pass through unchanged. */\n    resolvePath(baseDir: string, candidate: string): string {\n        if (isAbsolute(candidate)) return candidate;\n        return join(baseDir, candidate);\n    }\n\n    /** Writes each key to `process.env`, backing `Envapter.syncProcessEnv`. */\n    writeVars(vars: Record<string, string>): void {\n        for (const [key, value] of Object.entries(vars)) {\n            process.env[key] = value;\n        }\n    }\n}\n"],"mappings":"+LAcA,IAAa,EAAb,KAAqD,CAEjD,cAAyB,GAGzB,UAAmC,CAE/B,MAAO,CAAE,GAAIA,EAAAA,QAAQ,GAA+B,CACxD,CAGA,SAAS,EAAc,EAAsC,CACzD,GAAI,CAEA,OAAOC,EAAAA,QAAG,aAAa,EAAM,CAA0B,CAC3D,MAAQ,CACJ,MACJ,CACJ,CAOA,iBAAiB,EAA6B,CAG1C,OAFI,aAAiB,KACjB,EAAM,WAAW,OAAO,GAAG,EAAOC,EAAAA,QAAAA,EAAAA,EAAQC,EAAAA,cAAAA,CAAc,CAAK,CAAC,GAClE,EAAOC,EAAAA,QAAAA,CAAQ,CAAK,CACxB,CAGA,YAAY,EAAiB,EAA2B,CAEpD,OADA,EAAIC,EAAAA,WAAAA,CAAW,CAAS,EAAU,GAClC,EAAOC,EAAAA,KAAAA,CAAK,EAAS,CAAS,CAClC,CAGA,UAAU,EAAoC,CAC1C,IAAK,GAAM,CAAC,EAAK,KAAU,OAAO,QAAQ,CAAI,EAC1C,EAAA,QAAQ,IAAI,GAAO,CAE3B,CACJ"}

package/dist/portable/converters/BuiltInConverters.mjs

@@ -1,2 +1,2 @@
-import{EnvaptError as e}from"../infra/Error.mjs";const t=1e3,n=60*t,r=60*n,i=24*r,a={ms:1,s:t,m:n,h:r,d:i,w:7*i},o=new RegExp(String.raw`^(\d+(?:\.\d+)?)(ms|s|m|h|d|w)?$`,`u`),s=new RegExp(String.raw`^(\d+(?:\.\d+)?)(ms|s|m|h|d|w)$`,`u`),c=RegExp("^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$",`u`),l=65535;function u(e,t=!1){let n=e.match(t?s:o);if(!n)return;let[,r,i]=n;if(!r)return;let c=Number.parseFloat(r);if(!Number.isNaN(c))return c*a[i??`ms`]}function d(e){let t=e.trim();return t===``?void 0:Number(t)}var f=class t{static string(e,t){return String(e)}static number(e,t){let n=Number(e);return Number.isNaN(n)?t:n}static boolean(e,t){let n=e.toLowerCase().trim();return[`1`,`yes`,`true`,`on`].includes(n)?!0:[`0`,`no`,`false`,`off`].includes(n)?!1:t}static bigint(e,t){try{return BigInt(e)}catch{return t}}static symbol(e,t){try{return e?Symbol.for(e):t}catch{return t}}static integer(e,t){let n=d(e);return n!==void 0&&Number.isSafeInteger(n)?n:t}static float(e,t){let n=d(e);return n!==void 0&&!Number.isNaN(n)?n:t}static json(e,t){try{return JSON.parse(e)}catch{return t}}static url(e,t){try{return new URL(e)}catch{return t}}static regexp(e,t){try{let t=e.match(new RegExp(String.raw`^\/(.+)\/([gimsuvy]*)$`));return t?new RegExp(t[1],t[2]):new RegExp(e)}catch{return t}}static date(e,t){if(new RegExp(String.raw`^\d+$`).test(e)){let n=new Date(parseInt(e,10));return Number.isNaN(n.getTime())?t:n}if(!new RegExp(String.raw`^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$`,`u`).test(e))return t;let n=new Date(e);return Number.isNaN(n.getTime())?t:n}static time(t,n){let r=u(t);if(r!==void 0)return r;if(typeof n==`number`)return n;if(typeof n==`string`){let t=u(n,!0);if(t===void 0)throw new e(105,`Time-string fallback "${n}" is not a valid format. Expected <number><unit> where unit is one of: ms, s, m, h, d, w.`);return t}}static port(e,t){let n=d(e);return n!==void 0&&Number.isSafeInteger(n)&&n>=0&&n<=65535?n:t}static email(e,t){return c.test(e)?e:t}static processArrayConverter(n,r,i=!1){if(n.trim()===``)return[];let a=n.split(r.delimiter).map(e=>String(e).trim());if(i){let t=a.findIndex(e=>e===``);if(t!==-1)throw new e(207,`Array element at index ${t} is empty or whitespace only (strict mode).`)}let o=a.filter(Boolean);if(!o.length)return[];let s=r.of;if(typeof s==`function`)return o.map((t,n)=>{let r=s(t);if(r===void 0)throw new e(206,`Custom element converter returned undefined for item "${t}" at index ${n}.`);return r});let c=t.getConverter(s);return o.map((t,n)=>{let r=c(t,void 0);if(r===void 0)throw new e(206,`Element "${t}" at index ${n} could not be converted to ${s}.`);return r})}static getConverter(e){return{string:t.string,number:t.number,boolean:t.boolean,integer:t.integer,bigint:t.bigint,symbol:t.symbol,float:t.float,json:t.json,url:t.url,regexp:t.regexp,date:t.date,time:t.time,port:t.port,email:t.email}[e]}};export{f as BuiltInConverters,c as EMAIL_RE,l as MAX_PORT};
+import{EnvaptError as e}from"../infra/Error.mjs";const t=1e3,n=60*t,r=60*n,i=24*r,a={ms:1,s:t,m:n,h:r,d:i,w:7*i},o=new RegExp(String.raw`^(\d+(?:\.\d+)?)(ms|s|m|h|d|w)?$`,`u`),s=new RegExp(String.raw`^(\d+(?:\.\d+)?)(ms|s|m|h|d|w)$`,`u`),c=RegExp("^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$",`u`),l=65535;function u(e,t=!1){let n=e.match(t?s:o);if(!n)return;let[,r,i]=n;if(!r)return;let c=Number.parseFloat(r);if(!Number.isNaN(c))return c*a[i??`ms`]}function d(e){let t=e.trim();return t===``?void 0:Number(t)}var f=class t{static string(e,t){return String(e)}static number(e,t){let n=Number(e);return Number.isNaN(n)?t:n}static boolean(e,t){let n=e.toLowerCase().trim();return[`1`,`yes`,`true`,`on`].includes(n)?!0:![`0`,`no`,`false`,`off`].includes(n)&&t}static bigint(e,t){try{return BigInt(e)}catch{return t}}static symbol(e,t){try{return e?Symbol.for(e):t}catch{return t}}static integer(e,t){let n=d(e);return n!==void 0&&Number.isSafeInteger(n)?n:t}static float(e,t){let n=d(e);return n!==void 0&&!Number.isNaN(n)?n:t}static json(e,t){try{return JSON.parse(e)}catch{return t}}static url(e,t){try{return new URL(e)}catch{return t}}static regexp(e,t){try{let t=e.match(new RegExp(String.raw`^\/(.+)\/([gimsuvy]*)$`));return t?new RegExp(t[1],t[2]):new RegExp(e)}catch{return t}}static date(e,t){if(new RegExp(String.raw`^\d+$`).test(e)){let n=new Date(parseInt(e,10));return Number.isNaN(n.getTime())?t:n}if(!new RegExp(String.raw`^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$`,`u`).test(e))return t;let n=new Date(e);return Number.isNaN(n.getTime())?t:n}static time(t,n){let r=u(t);if(r!==void 0)return r;if(typeof n==`number`)return n;if(typeof n==`string`){let t=u(n,!0);if(t===void 0)throw new e(105,`Time-string fallback "${n}" is not a valid format. Expected <number><unit> where unit is one of: ms, s, m, h, d, w.`);return t}}static port(e,t){let n=d(e);return n!==void 0&&Number.isSafeInteger(n)&&n>=0&&n<=65535?n:t}static email(e,t){return c.test(e)?e:t}static processArrayConverter(n,r,i=!1){if(n.trim()===``)return[];let a=n.split(r.delimiter).map(e=>String(e).trim());if(i){let t=a.findIndex(e=>e===``);if(t!==-1)throw new e(207,`Array element at index ${t} is empty or whitespace only (strict mode).`)}let o=a.filter(Boolean);if(!o.length)return[];let s=r.of;if(typeof s==`function`)return o.map((t,n)=>{let r=s(t);if(r===void 0)throw new e(206,`Custom element converter returned undefined for item "${t}" at index ${n}.`);return r});let c=t.getConverter(s);return o.map((t,n)=>{let r=c(t,void 0);if(r===void 0)throw new e(206,`Element "${t}" at index ${n} could not be converted to ${s}.`);return r})}static getConverter(e){return{string:t.string,number:t.number,boolean:t.boolean,integer:t.integer,bigint:t.bigint,symbol:t.symbol,float:t.float,json:t.json,url:t.url,regexp:t.regexp,date:t.date,time:t.time,port:t.port,email:t.email}[e]}};export{f as BuiltInConverters,c as EMAIL_RE,l as MAX_PORT};
 //# sourceMappingURL=BuiltInConverters.mjs.map

package/dist/portable/converters/BuiltInConverters.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"BuiltInConverters.mjs","names":["converter"],"sources":["../../../src/converters/BuiltInConverters.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/unbound-method */\n\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { ArrayOf, CustomElementConverter } from './Converters';\nimport type {\n    BuiltInConverter,\n    BuiltInConverterFunction,\n    JsonValue,\n    MapOfConverterFunctions,\n    TimeFallback,\n    TimeUnit\n} from '../types';\n\nconst MS_PER_SECOND = 1000;\nconst SECONDS_PER_MINUTE = 60;\nconst MINUTES_PER_HOUR = 60;\nconst HOURS_PER_DAY = 24;\nconst DAYS_PER_WEEK = 7;\nconst MS_PER_MINUTE = SECONDS_PER_MINUTE * MS_PER_SECOND;\nconst MS_PER_HOUR = MINUTES_PER_HOUR * MS_PER_MINUTE;\nconst MS_PER_DAY = HOURS_PER_DAY * MS_PER_HOUR;\nconst MS_PER_WEEK = DAYS_PER_WEEK * MS_PER_DAY;\n\nconst TIME_UNIT_MS: Record<TimeUnit, number> = {\n    ms: 1,\n    s: MS_PER_SECOND,\n    m: MS_PER_MINUTE,\n    h: MS_PER_HOUR,\n    d: MS_PER_DAY,\n    w: MS_PER_WEEK\n};\n\nconst TIME_LOOSE_RE = new RegExp(String.raw`^(\\d+(?:\\.\\d+)?)(ms|s|m|h|d|w)?$`, 'u');\nconst TIME_STRICT_RE = new RegExp(String.raw`^(\\d+(?:\\.\\d+)?)(ms|s|m|h|d|w)$`, 'u');\n\n// WHATWG input[type=email] pattern. Full RFC 5322 rejects addresses people use.\n// eslint-disable-next-line security/detect-unsafe-regex -- bounded quantifiers, each label anchored by a literal dot, linear match (no ReDoS)\nexport const EMAIL_RE = new RegExp(\n    \"^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\\\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$\",\n    'u'\n);\n\nexport const MAX_PORT = 65535;\n\n/**\n * Parse a time string (e.g. `\"30s\"`, `\"1.5h\"`) into milliseconds.\n *\n * @param input - The string to parse.\n * @param strict - When `true`, require an explicit unit (used for fallback strings).\n *                 When `false` (default), treat a missing unit as `ms` (used for raw env values). Both allow decimals.\n * @returns The duration in milliseconds, or `undefined` if the input does not match the expected format.\n * @internal\n */\nfunction parseTimeString(input: string, strict = false): number | undefined {\n    const match = input.match(strict ? TIME_STRICT_RE : TIME_LOOSE_RE);\n    if (!match) return undefined;\n\n    const [, numStr, capturedUnit] = match;\n    if (!numStr) return undefined;\n\n    const value = Number.parseFloat(numStr);\n    if (Number.isNaN(value)) return undefined;\n\n    const unit = (capturedUnit ?? 'ms') as TimeUnit;\n    return value * TIME_UNIT_MS[unit];\n}\n\n// undefined for an empty or whitespace-only value, so each numeric converter maps that to its own fallback\nfunction parseTrimmedNumber(raw: string): number | undefined {\n    const trimmed = raw.trim();\n    return trimmed === '' ? undefined : Number(trimmed);\n}\n\n/**\n * Built-in converter implementations\n * @internal\n */\n// eslint-disable-next-line @typescript-eslint/no-extraneous-class -- dispatch-table helper, the documented exception to the no-static-class rule\nexport class BuiltInConverters {\n    static string(raw: string, _fallback?: string): string | undefined {\n        return String(raw);\n    }\n\n    static number(raw: string, fallback?: number): number | undefined {\n        const parsed = Number(raw);\n        return Number.isNaN(parsed) ? fallback : parsed;\n    }\n\n    static boolean(raw: string, fallback?: boolean): boolean | undefined {\n        const lower = raw.toLowerCase().trim();\n\n        const truthyValues = ['1', 'yes', 'true', 'on'];\n        const falsyValues = ['0', 'no', 'false', 'off'];\n\n        if (truthyValues.includes(lower)) return true;\n        if (falsyValues.includes(lower)) return false;\n        return fallback;\n    }\n\n    static bigint(raw: string, fallback?: bigint): bigint | undefined {\n        try {\n            return BigInt(raw);\n        } catch {\n            return fallback;\n        }\n    }\n\n    static symbol(raw: string, fallback?: symbol): symbol | undefined {\n        try {\n            return raw ? Symbol.for(raw) : fallback;\n        } catch {\n            return fallback;\n        }\n    }\n\n    static integer(raw: string, fallback?: number): number | undefined {\n        const parsed = parseTrimmedNumber(raw);\n        // isSafeInteger also guards the 2^53 boundary, past which an integer value silently loses precision.\n        return parsed !== undefined && Number.isSafeInteger(parsed) ? parsed : fallback;\n    }\n\n    static float(raw: string, fallback?: number): number | undefined {\n        const parsed = parseTrimmedNumber(raw);\n        // isNaN keeps Infinity valid, matching the number converter.\n        return parsed !== undefined && !Number.isNaN(parsed) ? parsed : fallback;\n    }\n\n    static json(raw: string, fallback?: JsonValue): JsonValue | undefined {\n        try {\n            return JSON.parse(raw) as JsonValue;\n        } catch {\n            return fallback;\n        }\n    }\n\n    static url(raw: string, fallback?: URL): URL | undefined {\n        try {\n            return new URL(raw);\n        } catch {\n            return fallback;\n        }\n    }\n\n    static regexp(raw: string, fallback?: RegExp): RegExp | undefined {\n        try {\n            // Handle flags if provided in format: /pattern/flags\n            const match = raw.match(new RegExp(String.raw`^\\/(.+)\\/([gimsuvy]*)$`));\n            if (match) return new RegExp(match[1] as string, match[2]);\n\n            return new RegExp(raw);\n        } catch {\n            return fallback;\n        }\n    }\n\n    static date(raw: string, fallback?: Date): Date | undefined {\n        // Try parsing as timestamp first (if it's all digits)\n        if (new RegExp(String.raw`^\\d+$`).test(raw)) {\n            const timestamp = parseInt(raw, 10);\n            const parsed = new Date(timestamp);\n            return Number.isNaN(parsed.getTime()) ? fallback : parsed;\n        }\n\n        // Only accept ISO 8601 date strings (strict format)\n        const isoRegex = new RegExp(String.raw`^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z$`, 'u');\n        if (!isoRegex.test(raw)) return fallback;\n\n        const parsed = new Date(raw);\n        return Number.isNaN(parsed.getTime()) ? fallback : parsed;\n    }\n\n    static time(raw: string, fallback?: TimeFallback): number | undefined {\n        const parsedRaw = parseTimeString(raw);\n        if (parsedRaw !== undefined) return parsedRaw;\n\n        // Raw didn't parse so apply fallback\n        if (typeof fallback === 'number') return fallback;\n        if (typeof fallback === 'string') {\n            // A string fallback must name a unit; a unitless number is expressed as a number fallback, not a string.\n            const parsedFallback = parseTimeString(fallback, true);\n            if (parsedFallback === undefined) {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.MalformedTimeFallback,\n                    `Time-string fallback \"${fallback}\" is not a valid format. Expected <number><unit> where unit is one of: ms, s, m, h, d, w.`\n                );\n            }\n            return parsedFallback;\n        }\n        return undefined;\n    }\n\n    static port(raw: string, fallback?: number): number | undefined {\n        const parsed = parseTrimmedNumber(raw);\n        // 0 is the ephemeral-bind wildcard\n        return parsed !== undefined && Number.isSafeInteger(parsed) && parsed >= 0 && parsed <= MAX_PORT\n            ? parsed\n            : fallback;\n    }\n\n    static email(raw: string, fallback?: string): string | undefined {\n        return EMAIL_RE.test(raw) ? raw : fallback;\n    }\n\n    static processArrayConverter(raw: string, config: ArrayOf, strict = false): unknown[] {\n        if (raw.trim() === '') return [];\n\n        const trimmedItems = raw.split(config.delimiter).map((item) => String(item).trim());\n\n        // strict rejects an empty item that the default filter below drops silently\n        if (strict) {\n            const emptyIdx = trimmedItems.findIndex((item) => item === '');\n            if (emptyIdx !== -1) {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.EmptyArrayElement,\n                    `Array element at index ${emptyIdx} is empty or whitespace only (strict mode).`\n                );\n            }\n        }\n\n        const items = trimmedItems.filter(Boolean);\n\n        if (!items.length) return [];\n\n        const elementOf = config.of;\n\n        if (typeof elementOf === 'function') {\n            return items.map((item, index) => {\n                const converter = elementOf as CustomElementConverter;\n                const result = converter(item);\n                if (result === undefined) {\n                    throw new EnvaptError(\n                        EnvaptErrorCodes.ArrayElementConversionFailed,\n                        `Custom element converter returned undefined for item \"${item}\" at index ${index}.`\n                    );\n                }\n                return result;\n            });\n        }\n\n        const converter = BuiltInConverters.getConverter(elementOf);\n        return items.map((item, index) => {\n            const converted = converter(item, undefined);\n            if (converted === undefined) {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.ArrayElementConversionFailed,\n                    `Element \"${item}\" at index ${index} could not be converted to ${elementOf}.`\n                );\n            }\n            return converted;\n        });\n    }\n\n    /**\n     * Get the converter function for a built-in converter type\n     */\n    static getConverter<TFallback extends BuiltInConverter>(type: TFallback): BuiltInConverterFunction {\n        const converters: MapOfConverterFunctions = {\n            string: BuiltInConverters.string,\n            number: BuiltInConverters.number,\n            boolean: BuiltInConverters.boolean,\n            integer: BuiltInConverters.integer,\n            bigint: BuiltInConverters.bigint,\n            symbol: BuiltInConverters.symbol,\n            float: BuiltInConverters.float,\n            json: BuiltInConverters.json,\n            url: BuiltInConverters.url,\n            regexp: BuiltInConverters.regexp,\n            date: BuiltInConverters.date,\n            time: BuiltInConverters.time,\n            port: BuiltInConverters.port,\n            email: BuiltInConverters.email\n        } as const;\n\n        return converters[type];\n    }\n}\n"],"mappings":"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"}
+{"version":3,"file":"BuiltInConverters.mjs","names":["converter"],"sources":["../../../src/converters/BuiltInConverters.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/unbound-method */\n\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { ArrayOf, CustomElementConverter } from './Converters';\nimport type {\n    BuiltInConverter,\n    BuiltInConverterFunction,\n    JsonValue,\n    MapOfConverterFunctions,\n    TimeFallback,\n    TimeUnit\n} from '../types';\n\nconst MS_PER_SECOND = 1000;\nconst SECONDS_PER_MINUTE = 60;\nconst MINUTES_PER_HOUR = 60;\nconst HOURS_PER_DAY = 24;\nconst DAYS_PER_WEEK = 7;\nconst MS_PER_MINUTE = SECONDS_PER_MINUTE * MS_PER_SECOND;\nconst MS_PER_HOUR = MINUTES_PER_HOUR * MS_PER_MINUTE;\nconst MS_PER_DAY = HOURS_PER_DAY * MS_PER_HOUR;\nconst MS_PER_WEEK = DAYS_PER_WEEK * MS_PER_DAY;\n\nconst TIME_UNIT_MS: Record<TimeUnit, number> = {\n    ms: 1,\n    s: MS_PER_SECOND,\n    m: MS_PER_MINUTE,\n    h: MS_PER_HOUR,\n    d: MS_PER_DAY,\n    w: MS_PER_WEEK\n};\n\nconst TIME_LOOSE_RE = new RegExp(String.raw`^(\\d+(?:\\.\\d+)?)(ms|s|m|h|d|w)?$`, 'u');\nconst TIME_STRICT_RE = new RegExp(String.raw`^(\\d+(?:\\.\\d+)?)(ms|s|m|h|d|w)$`, 'u');\n\n// WHATWG input[type=email] pattern. Full RFC 5322 rejects addresses people use.\n// eslint-disable-next-line security/detect-unsafe-regex -- bounded quantifiers, each label anchored by a literal dot, linear match (no ReDoS)\nexport const EMAIL_RE = new RegExp(\n    \"^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\\\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$\",\n    'u'\n);\n\nexport const MAX_PORT = 65535;\n\n/**\n * Parse a time string (e.g. `\"30s\"`, `\"1.5h\"`) into milliseconds.\n *\n * @param input - The string to parse.\n * @param strict - When `true`, require an explicit unit (used for fallback strings).\n *                 When `false` (default), treat a missing unit as `ms` (used for raw env values). Both allow decimals.\n * @returns The duration in milliseconds, or `undefined` if the input does not match the expected format.\n * @internal\n */\nfunction parseTimeString(input: string, strict = false): number | undefined {\n    const match = input.match(strict ? TIME_STRICT_RE : TIME_LOOSE_RE);\n    if (!match) return undefined;\n\n    const [, numStr, capturedUnit] = match;\n    if (!numStr) return undefined;\n\n    const value = Number.parseFloat(numStr);\n    if (Number.isNaN(value)) return undefined;\n\n    const unit = (capturedUnit ?? 'ms') as TimeUnit;\n    return value * TIME_UNIT_MS[unit];\n}\n\n// undefined for an empty or whitespace-only value, so each numeric converter maps that to its own fallback\nfunction parseTrimmedNumber(raw: string): number | undefined {\n    const trimmed = raw.trim();\n    return trimmed === '' ? undefined : Number(trimmed);\n}\n\n/**\n * Built-in converter implementations\n * @internal\n */\n// eslint-disable-next-line @typescript-eslint/no-extraneous-class -- dispatch-table helper, the documented exception to the no-static-class rule\nexport class BuiltInConverters {\n    static string(raw: string, _fallback?: string): string | undefined {\n        return String(raw);\n    }\n\n    static number(raw: string, fallback?: number): number | undefined {\n        const parsed = Number(raw);\n        return Number.isNaN(parsed) ? fallback : parsed;\n    }\n\n    static boolean(raw: string, fallback?: boolean): boolean | undefined {\n        const lower = raw.toLowerCase().trim();\n\n        const truthyValues = ['1', 'yes', 'true', 'on'];\n        const falsyValues = ['0', 'no', 'false', 'off'];\n\n        if (truthyValues.includes(lower)) return true;\n        if (falsyValues.includes(lower)) return false;\n        return fallback;\n    }\n\n    static bigint(raw: string, fallback?: bigint): bigint | undefined {\n        try {\n            return BigInt(raw);\n        } catch {\n            return fallback;\n        }\n    }\n\n    static symbol(raw: string, fallback?: symbol): symbol | undefined {\n        try {\n            return raw ? Symbol.for(raw) : fallback;\n        } catch {\n            return fallback;\n        }\n    }\n\n    static integer(raw: string, fallback?: number): number | undefined {\n        const parsed = parseTrimmedNumber(raw);\n        // isSafeInteger also guards the 2^53 boundary, past which an integer value silently loses precision.\n        return parsed !== undefined && Number.isSafeInteger(parsed) ? parsed : fallback;\n    }\n\n    static float(raw: string, fallback?: number): number | undefined {\n        const parsed = parseTrimmedNumber(raw);\n        // isNaN keeps Infinity valid, matching the number converter.\n        return parsed !== undefined && !Number.isNaN(parsed) ? parsed : fallback;\n    }\n\n    static json(raw: string, fallback?: JsonValue): JsonValue | undefined {\n        try {\n            return JSON.parse(raw) as JsonValue;\n        } catch {\n            return fallback;\n        }\n    }\n\n    static url(raw: string, fallback?: URL): URL | undefined {\n        try {\n            return new URL(raw);\n        } catch {\n            return fallback;\n        }\n    }\n\n    static regexp(raw: string, fallback?: RegExp): RegExp | undefined {\n        try {\n            // Handle flags if provided in format: /pattern/flags\n            const match = raw.match(new RegExp(String.raw`^\\/(.+)\\/([gimsuvy]*)$`));\n            if (match) return new RegExp(match[1] as string, match[2]);\n\n            return new RegExp(raw);\n        } catch {\n            return fallback;\n        }\n    }\n\n    static date(raw: string, fallback?: Date): Date | undefined {\n        // Try parsing as timestamp first (if it's all digits)\n        if (new RegExp(String.raw`^\\d+$`).test(raw)) {\n            const timestamp = parseInt(raw, 10);\n            const parsed = new Date(timestamp);\n            return Number.isNaN(parsed.getTime()) ? fallback : parsed;\n        }\n\n        // Only accept ISO 8601 date strings (strict format)\n        const isoRegex = new RegExp(String.raw`^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z$`, 'u');\n        if (!isoRegex.test(raw)) return fallback;\n\n        const parsed = new Date(raw);\n        return Number.isNaN(parsed.getTime()) ? fallback : parsed;\n    }\n\n    static time(raw: string, fallback?: TimeFallback): number | undefined {\n        const parsedRaw = parseTimeString(raw);\n        if (parsedRaw !== undefined) return parsedRaw;\n\n        // Raw didn't parse so apply fallback\n        if (typeof fallback === 'number') return fallback;\n        if (typeof fallback === 'string') {\n            // A string fallback must name a unit; a unitless number is expressed as a number fallback, not a string.\n            const parsedFallback = parseTimeString(fallback, true);\n            if (parsedFallback === undefined) {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.MalformedTimeFallback,\n                    `Time-string fallback \"${fallback}\" is not a valid format. Expected <number><unit> where unit is one of: ms, s, m, h, d, w.`\n                );\n            }\n            return parsedFallback;\n        }\n        return undefined;\n    }\n\n    static port(raw: string, fallback?: number): number | undefined {\n        const parsed = parseTrimmedNumber(raw);\n        // 0 is the ephemeral-bind wildcard\n        return parsed !== undefined && Number.isSafeInteger(parsed) && parsed >= 0 && parsed <= MAX_PORT\n            ? parsed\n            : fallback;\n    }\n\n    static email(raw: string, fallback?: string): string | undefined {\n        return EMAIL_RE.test(raw) ? raw : fallback;\n    }\n\n    static processArrayConverter(raw: string, config: ArrayOf, strict = false): unknown[] {\n        if (raw.trim() === '') return [];\n\n        const trimmedItems = raw.split(config.delimiter).map((item) => String(item).trim());\n\n        // strict rejects an empty item that the default filter below drops silently\n        if (strict) {\n            const emptyIdx = trimmedItems.findIndex((item) => item === '');\n            if (emptyIdx !== -1) {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.EmptyArrayElement,\n                    `Array element at index ${emptyIdx} is empty or whitespace only (strict mode).`\n                );\n            }\n        }\n\n        const items = trimmedItems.filter(Boolean);\n\n        if (!items.length) return [];\n\n        const elementOf = config.of;\n\n        if (typeof elementOf === 'function') {\n            return items.map((item, index) => {\n                const converter = elementOf as CustomElementConverter;\n                const result = converter(item);\n                if (result === undefined) {\n                    throw new EnvaptError(\n                        EnvaptErrorCodes.ArrayElementConversionFailed,\n                        `Custom element converter returned undefined for item \"${item}\" at index ${index}.`\n                    );\n                }\n                return result;\n            });\n        }\n\n        const converter = BuiltInConverters.getConverter(elementOf);\n        return items.map((item, index) => {\n            const converted = converter(item, undefined);\n            if (converted === undefined) {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.ArrayElementConversionFailed,\n                    `Element \"${item}\" at index ${index} could not be converted to ${elementOf}.`\n                );\n            }\n            return converted;\n        });\n    }\n\n    /**\n     * Get the converter function for a built-in converter type\n     */\n    static getConverter<TFallback extends BuiltInConverter>(type: TFallback): BuiltInConverterFunction {\n        const converters: MapOfConverterFunctions = {\n            string: BuiltInConverters.string,\n            number: BuiltInConverters.number,\n            boolean: BuiltInConverters.boolean,\n            integer: BuiltInConverters.integer,\n            bigint: BuiltInConverters.bigint,\n            symbol: BuiltInConverters.symbol,\n            float: BuiltInConverters.float,\n            json: BuiltInConverters.json,\n            url: BuiltInConverters.url,\n            regexp: BuiltInConverters.regexp,\n            date: BuiltInConverters.date,\n            time: BuiltInConverters.time,\n            port: BuiltInConverters.port,\n            email: BuiltInConverters.email\n        } as const;\n\n        return converters[type];\n    }\n}\n"],"mappings":"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"}

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

@@ -1 +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 { isMissing } from './missing';\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    // An ordered read keeps trying so a present-but-empty candidate falls through to the next, matching\n    // getRequired and firstEnvKeyValue. A single key or an all-empty list resolves to the first present value.\n    let firstPresent: { key: string; value: string } | undefined;\n    for (const candidate of normalizedKeys) {\n        const value = readCached(candidate);\n        if (value === undefined) continue;\n        if (!isMissing(value)) return { key: candidate, value };\n        firstPresent ??= { key: candidate, value };\n    }\n\n    return firstPresent ?? { key: normalizedKeys[0] as string, value: undefined };\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\nfunction readCached(key: string): string | undefined {\n    const c = ensureLoaded();\n    // decorator memoization also stores non-string values in this shared cache\n    if (c.has(key)) {\n        const cached = c.get(key);\n        return typeof cached === 'string' ? cached : undefined;\n    }\n    const source = state.source;\n    if (typeof source.readVar !== 'function') return undefined;\n    const value = source.readVar(key);\n    // cache a miss too, so a later read of an absent key skips the reader\n    c.set(key, value);\n    return value;\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) => readCached(key));\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\nconst PRIMITIVE_NAMES: Record<Primitive, string> = {\n    [Primitive.String]: 'string',\n    [Primitive.Number]: 'number',\n    [Primitive.Boolean]: 'boolean',\n    [Primitive.BigInt]: 'bigint',\n    [Primitive.Symbol]: '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 (isMissing(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 converted: EnvVarReturnType | undefined;\n    if (type === Primitive.Number) converted = BuiltInConverters.number(parsed) as EnvVarReturnType | undefined;\n    else if (type === Primitive.Boolean) converted = BuiltInConverters.boolean(parsed) as EnvVarReturnType | undefined;\n    else if (type === Primitive.BigInt) converted = BuiltInConverters.bigint(parsed) as EnvVarReturnType | undefined;\n    else if (type === Primitive.Symbol) converted = BuiltInConverters.symbol(parsed) as EnvVarReturnType | undefined;\n    else converted = BuiltInConverters.string(parsed) as EnvVarReturnType | undefined;\n\n    if (converted === undefined) {\n        // key and type only, no value: env values can be secrets and verbose logs reach stderr\n        debugVerbose(\n            `could not convert ${resolvedKey} as ${PRIMITIVE_NAMES[type]}${def !== undefined ? ', using the fallback' : ''}`\n        );\n        return def as ConditionalReturn<EnvVarReturnType, DefaultType>;\n    }\n\n    return converted;\n}\n"],"mappings":"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"}
+{"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 { isMissing } from './missing';\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    // An ordered read keeps trying so a present-but-empty candidate falls through to the next, matching\n    // getRequired and firstEnvKeyValue. A single key or an all-empty list resolves to the first present value.\n    let firstPresent: { key: string; value: string } | undefined;\n    for (const candidate of normalizedKeys) {\n        const value = readCached(candidate);\n        if (value === undefined) continue;\n        if (!isMissing(value)) return { key: candidate, value };\n        firstPresent ??= { key: candidate, value };\n    }\n\n    return firstPresent ?? { key: normalizedKeys[0] as string, value: undefined };\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\nfunction readCached(key: string): string | undefined {\n    const c = ensureLoaded();\n    // decorator memoization also stores non-string values in this shared cache\n    if (c.has(key)) {\n        const cached = c.get(key);\n        return typeof cached === 'string' ? cached : undefined;\n    }\n    const source = state.source;\n    if (typeof source.readVar !== 'function') return undefined;\n    const value = source.readVar(key);\n    // cache a miss too, so a later read of an absent key skips the reader\n    c.set(key, value);\n    return value;\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) => readCached(key));\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\nconst PRIMITIVE_NAMES: Record<Primitive, string> = {\n    [Primitive.String]: 'string',\n    [Primitive.Number]: 'number',\n    [Primitive.Boolean]: 'boolean',\n    [Primitive.BigInt]: 'bigint',\n    [Primitive.Symbol]: '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 (isMissing(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 converted: EnvVarReturnType | undefined;\n    if (type === Primitive.Number) converted = BuiltInConverters.number(parsed) as EnvVarReturnType | undefined;\n    else if (type === Primitive.Boolean) converted = BuiltInConverters.boolean(parsed) as EnvVarReturnType | undefined;\n    else if (type === Primitive.BigInt) converted = BuiltInConverters.bigint(parsed) as EnvVarReturnType | undefined;\n    else if (type === Primitive.Symbol) converted = BuiltInConverters.symbol(parsed) as EnvVarReturnType | undefined;\n    else converted = BuiltInConverters.string(parsed) as EnvVarReturnType | undefined;\n\n    if (converted === undefined) {\n        // key and type only, no value: env values can be secrets and verbose logs reach stderr\n        debugVerbose(\n            `could not convert ${resolvedKey} as ${PRIMITIVE_NAMES[type]}${def !== undefined ? ', using the fallback' : ''}`\n        );\n        return def as ConditionalReturn<EnvVarReturnType, DefaultType>;\n    }\n\n    return converted;\n}\n"],"mappings":"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"}

package/dist/portable/core/paths.mjs

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

package/dist/portable/decorators/legacy/createPropertyDecorator.mjs

@@ -1,2 +1,2 @@
-import{EnvaptError as e}from"../../infra/Error.mjs";import{decoratorCacheKey as t,resolveDecoratorValue as n}from"../resolveDecoratorValue.mjs";function r(r,i){return function(a,o){let s=String(o),c=typeof a==`function`,l=t(c?a:a.constructor,c,s);Object.defineProperty(a,s,{get:function(){return n(r,i,l)},set(){throw new e(302,`Cannot assign to "${s}". @Envapt properties resolve from the environment and are read-only.`)},configurable:!1,enumerable:!0})}}export{r as createPropertyDecorator};
+import{EnvaptError as e}from"../../infra/Error.mjs";import{decoratorCacheKey as t,resolveDecoratorValue as n}from"../resolveDecoratorValue.mjs";function r(r,i){return function(a,o){let s=String(o),c=typeof a==`function`,l=c?a:a.constructor,u=t(l,c,s);Object.defineProperty(a,s,{get:function(){return n(r,i,u)},set(){throw new e(302,`Cannot assign to "${s}". @Envapt properties resolve from the environment and are read-only.`)},configurable:!1,enumerable:!0})}}export{r as createPropertyDecorator};
 //# sourceMappingURL=createPropertyDecorator.mjs.map

package/dist/portable/decorators/legacy/createPropertyDecorator.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"createPropertyDecorator.mjs","names":[],"sources":["../../../../src/decorators/legacy/createPropertyDecorator.ts"],"sourcesContent":["import { EnvaptError, EnvaptErrorCodes } from '../../infra/Error';\nimport { decoratorCacheKey, resolveDecoratorValue } from '../resolveDecoratorValue';\n\nimport type { EnvKeyInput } from '../../types';\nimport type { DecoratorConfig } from '../resolveDecoratorValue';\n\nexport function createPropertyDecorator<TFallback>(\n    key: EnvKeyInput,\n    config: DecoratorConfig<TFallback>\n): PropertyDecorator {\n    return function (target: object, prop: string | symbol): void {\n        const propKey = String(prop);\n        const isStatic = typeof target === 'function';\n        const owner = isStatic ? target : target.constructor;\n        const cacheKey = decoratorCacheKey(owner, isStatic, propKey);\n\n        Object.defineProperty(target, propKey, {\n            get: function () {\n                return resolveDecoratorValue(key, config, cacheKey);\n            },\n            set(): void {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.InvalidUserDefinedConfig,\n                    `Cannot assign to \"${propKey}\". @Envapt properties resolve from the environment and are read-only.`\n                );\n            },\n            configurable: false,\n            enumerable: true\n        });\n    };\n}\n"],"mappings":"gJAMA,SAAgB,EACZ,EACA,EACiB,CACjB,OAAO,SAAU,EAAgB,EAA6B,CAC1D,IAAM,EAAU,OAAO,CAAI,EACrB,EAAW,OAAO,GAAW,WAE7B,EAAW,EADH,EAAW,EAAS,EAAO,YACC,EAAU,CAAO,EAE3D,OAAO,eAAe,EAAQ,EAAS,CACnC,IAAK,UAAY,CACb,OAAO,EAAsB,EAAK,EAAQ,CAAQ,CACtD,EACA,KAAY,CACR,MAAM,IAAI,EAAA,IAEN,qBAAqB,EAAQ,sEACjC,CACJ,EACA,aAAc,GACd,WAAY,EAChB,CAAC,CACL,CACJ"}
+{"version":3,"file":"createPropertyDecorator.mjs","names":[],"sources":["../../../../src/decorators/legacy/createPropertyDecorator.ts"],"sourcesContent":["import { EnvaptError, EnvaptErrorCodes } from '../../infra/Error';\nimport { decoratorCacheKey, resolveDecoratorValue } from '../resolveDecoratorValue';\n\nimport type { EnvKeyInput } from '../../types';\nimport type { DecoratorConfig } from '../resolveDecoratorValue';\n\nexport function createPropertyDecorator<TFallback>(\n    key: EnvKeyInput,\n    config: DecoratorConfig<TFallback>\n): PropertyDecorator {\n    return function (target: object, prop: string | symbol): void {\n        const propKey = String(prop);\n        const isStatic = typeof target === 'function';\n        const owner = isStatic ? target : target.constructor;\n        const cacheKey = decoratorCacheKey(owner, isStatic, propKey);\n\n        Object.defineProperty(target, propKey, {\n            get: function () {\n                return resolveDecoratorValue(key, config, cacheKey);\n            },\n            set(): void {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.InvalidUserDefinedConfig,\n                    `Cannot assign to \"${propKey}\". @Envapt properties resolve from the environment and are read-only.`\n                );\n            },\n            configurable: false,\n            enumerable: true\n        });\n    };\n}\n"],"mappings":"gJAMA,SAAgB,EACZ,EACA,EACiB,CACjB,OAAO,SAAU,EAAgB,EAA6B,CAC1D,IAAM,EAAU,OAAO,CAAI,EACrB,EAAW,OAAO,GAAW,WAC7B,EAAQ,EAAW,EAAS,EAAO,YACnC,EAAW,EAAkB,EAAO,EAAU,CAAO,EAE3D,OAAO,eAAe,EAAQ,EAAS,CACnC,IAAK,UAAY,CACb,OAAO,EAAsB,EAAK,EAAQ,CAAQ,CACtD,EACA,KAAY,CACR,MAAM,IAAI,EAAA,IAEN,qBAAqB,EAAQ,sEACjC,CACJ,EACA,aAAc,GACd,WAAY,EAChB,CAAC,CACL,CACJ"}

package/dist/portable/decorators/modern/createAccessorDecorator.mjs

@@ -1,2 +1,2 @@
-import{EnvaptError as e}from"../../infra/Error.mjs";import{decoratorCacheKey as t,resolveDecoratorValue as n}from"../resolveDecoratorValue.mjs";function r(r,i){return function(a,o){let s=o.name;if(s===void 0)throw new e(302,`The runtime did not provide the accessor name to @Envapt, this Stage 3 decorator transform is unsupported.`);let c=String(s);return{get(){let e=this,a=typeof e==`function`;return n(r,i,t(a?e:e.constructor,a,c))},set(){throw new e(302,`Cannot assign to "${c}". @Envapt accessor properties resolve from the environment and are read-only.`)}}}}export{r as createAccessorDecorator};
+import{EnvaptError as e}from"../../infra/Error.mjs";import{decoratorCacheKey as t,resolveDecoratorValue as n}from"../resolveDecoratorValue.mjs";function r(r,i){return function(a,o){let s=o.name;if(s===void 0)throw new e(302,`The runtime did not provide the accessor name to @Envapt, this Stage 3 decorator transform is unsupported.`);let c=String(s);return{get(){let e=this,a=typeof e==`function`,o=a?e:e.constructor,s=t(o,a,c);return n(r,i,s)},set(){throw new e(302,`Cannot assign to "${c}". @Envapt accessor properties resolve from the environment and are read-only.`)}}}}export{r as createAccessorDecorator};
 //# sourceMappingURL=createAccessorDecorator.mjs.map

package/dist/portable/decorators/modern/createAccessorDecorator.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"createAccessorDecorator.mjs","names":[],"sources":["../../../../src/decorators/modern/createAccessorDecorator.ts"],"sourcesContent":["import { EnvaptError, EnvaptErrorCodes } from '../../infra/Error';\nimport { decoratorCacheKey, resolveDecoratorValue } from '../resolveDecoratorValue';\n\nimport type { EnvKeyInput } from '../../types';\nimport type { DecoratorConfig } from '../resolveDecoratorValue';\n\n/* v8 ignore start -- @preserve oxc (vitest's transform) breaks modern accessor decorators (context.name unset), so the tsc stage3-emit harness covers these, not vitest */\nexport function createAccessorDecorator<TFallback>(key: EnvKeyInput, config: DecoratorConfig<TFallback>) {\n    return function <This, Value>(\n        _target: ClassAccessorDecoratorTarget<This, Value>,\n        context: ClassAccessorDecoratorContext<This, Value>\n    ): ClassAccessorDecoratorResult<This, Value> {\n        const name: string | symbol | undefined = context.name;\n        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- a broken Stage 3 transform can leave context.name unset, which would collapse every accessor to one cache key\n        if (name === undefined) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidUserDefinedConfig,\n                'The runtime did not provide the accessor name to @Envapt, this Stage 3 decorator transform is unsupported.'\n            );\n        }\n        const propKey = String(name);\n\n        return {\n            get(this: This): Value {\n                const self = this as object;\n                // derive static-ness from `this` (the class is a function, an instance is not) rather than\n                // context.static, which some transformers (oxc) leave unset, collapsing every owner to Function\n                const isStatic = typeof self === 'function';\n                const owner = isStatic ? self : self.constructor;\n                const cacheKey = decoratorCacheKey(owner, isStatic, propKey);\n                return resolveDecoratorValue(key, config, cacheKey) as Value;\n            },\n            set(): void {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.InvalidUserDefinedConfig,\n                    `Cannot assign to \"${propKey}\". @Envapt accessor properties resolve from the environment and are read-only.`\n                );\n            }\n        };\n    };\n}\n/* v8 ignore stop */\n"],"mappings":"gJAOA,SAAgB,EAAmC,EAAkB,EAAoC,CACrG,OAAO,SACH,EACA,EACyC,CACzC,IAAM,EAAoC,EAAQ,KAElD,GAAI,IAAS,IAAA,GACT,MAAM,IAAI,EAAA,IAEN,4GACJ,EAEJ,IAAM,EAAU,OAAO,CAAI,EAE3B,MAAO,CACH,KAAuB,CACnB,IAAM,EAAO,KAGP,EAAW,OAAO,GAAS,WAGjC,OAAO,EAAsB,EAAK,EADjB,EADH,EAAW,EAAO,EAAK,YACK,EAAU,CACH,CAAC,CACtD,EACA,KAAY,CACR,MAAM,IAAI,EAAA,IAEN,qBAAqB,EAAQ,+EACjC,CACJ,CACJ,CACJ,CACJ"}
+{"version":3,"file":"createAccessorDecorator.mjs","names":[],"sources":["../../../../src/decorators/modern/createAccessorDecorator.ts"],"sourcesContent":["import { EnvaptError, EnvaptErrorCodes } from '../../infra/Error';\nimport { decoratorCacheKey, resolveDecoratorValue } from '../resolveDecoratorValue';\n\nimport type { EnvKeyInput } from '../../types';\nimport type { DecoratorConfig } from '../resolveDecoratorValue';\n\n/* v8 ignore start -- @preserve oxc (vitest's transform) breaks modern accessor decorators (context.name unset), so the tsc stage3-emit harness covers these, not vitest */\nexport function createAccessorDecorator<TFallback>(key: EnvKeyInput, config: DecoratorConfig<TFallback>) {\n    return function <This, Value>(\n        _target: ClassAccessorDecoratorTarget<This, Value>,\n        context: ClassAccessorDecoratorContext<This, Value>\n    ): ClassAccessorDecoratorResult<This, Value> {\n        const name: string | symbol | undefined = context.name;\n        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- a broken Stage 3 transform can leave context.name unset, which would collapse every accessor to one cache key\n        if (name === undefined) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidUserDefinedConfig,\n                'The runtime did not provide the accessor name to @Envapt, this Stage 3 decorator transform is unsupported.'\n            );\n        }\n        const propKey = String(name);\n\n        return {\n            get(this: This): Value {\n                const self = this as object;\n                // derive static-ness from `this` (the class is a function, an instance is not) rather than\n                // context.static, which some transformers (oxc) leave unset, collapsing every owner to Function\n                const isStatic = typeof self === 'function';\n                const owner = isStatic ? self : self.constructor;\n                const cacheKey = decoratorCacheKey(owner, isStatic, propKey);\n                return resolveDecoratorValue(key, config, cacheKey) as Value;\n            },\n            set(): void {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.InvalidUserDefinedConfig,\n                    `Cannot assign to \"${propKey}\". @Envapt accessor properties resolve from the environment and are read-only.`\n                );\n            }\n        };\n    };\n}\n/* v8 ignore stop */\n"],"mappings":"gJAOA,SAAgB,EAAmC,EAAkB,EAAoC,CACrG,OAAO,SACH,EACA,EACyC,CACzC,IAAM,EAAoC,EAAQ,KAElD,GAAI,IAAS,IAAA,GACT,MAAM,IAAI,EAAA,IAEN,4GACJ,EAEJ,IAAM,EAAU,OAAO,CAAI,EAE3B,MAAO,CACH,KAAuB,CACnB,IAAM,EAAO,KAGP,EAAW,OAAO,GAAS,WAC3B,EAAQ,EAAW,EAAO,EAAK,YAC/B,EAAW,EAAkB,EAAO,EAAU,CAAO,EAC3D,OAAO,EAAsB,EAAK,EAAQ,CAAQ,CACtD,EACA,KAAY,CACR,MAAM,IAAI,EAAA,IAEN,qBAAqB,EAAQ,+EACjC,CACJ,CACJ,CACJ,CACJ"}

package/dist/portable/decorators/resolveDecoratorValue.mjs

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

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

@@ -1 +1 @@
-{"version":3,"file":"resolveDecoratorValue.mjs","names":[],"sources":["../../../src/decorators/resolveDecoratorValue.ts"],"sourcesContent":["import { ValueConverter } from '../converters';\nimport { isMissing } from '../core/missing';\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's identity 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 | undefined {\n    const { fallback, converter, hasFallback, required, schema } = config;\n\n    // cache.has guards the read so a cached undefined counts as resolved (a converter returning\n    // undefined, or a missing no-fallback read) and later accesses skip re-resolving\n    if (cache.has(cacheKey)) return cache.get(cacheKey) as TFallback | undefined;\n\n    const envapter = new Envapter();\n\n    if (required && schema === undefined) {\n        const rawValue = envapter.getRaw(key);\n        if (isMissing(rawValue)) {\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":"+PAiBA,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,EACqB,CACrB,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,IAEnB,EADa,EAAS,OAAO,CACZ,CAAC,EAClB,MAAM,IAAI,EAAA,IAEN,kCAAkC,EAAkB,CAAG,EAAE,uBAC7D,EAIR,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"}
+{"version":3,"file":"resolveDecoratorValue.mjs","names":[],"sources":["../../../src/decorators/resolveDecoratorValue.ts"],"sourcesContent":["import { ValueConverter } from '../converters';\nimport { isMissing } from '../core/missing';\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's identity 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 | undefined {\n    const { fallback, converter, hasFallback, required, schema } = config;\n\n    // cache.has guards the read so a cached undefined counts as resolved (a converter returning\n    // undefined, or a missing no-fallback read) and later accesses skip re-resolving\n    if (cache.has(cacheKey)) return cache.get(cacheKey) as TFallback | undefined;\n\n    const envapter = new Envapter();\n\n    if (required && schema === undefined) {\n        const rawValue = envapter.getRaw(key);\n        if (isMissing(rawValue)) {\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":"+PAiBA,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,EACqB,CACrB,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,EAAU,CAAQ,EAClB,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/portable/engine/Envapter.mjs

@@ -1,2 +1,2 @@
-import{EnvaptError as e}from"../infra/Error.mjs";import"../core/Environment.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)}static has(r){try{return i(t(r),n).value!==void 0}catch(t){if(t instanceof e&&t.code===305)return!1;throw t}}has(e){return a.has(e)}};export{a as Envapter};
+import{EnvaptError as e}from"../infra/Error.mjs";import{Environment as t}from"../core/Environment.mjs";import{resolveKeyInput as n,templateResolver as r}from"../core/engine.mjs";import{AdvancedMethods as i,resolveRequired as a}from"../core/AdvancedMethods.mjs";var o=class t extends i{static resolve(n,...r){let i=t.strict;return n.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,...n){return t.resolve(e,...n)}static require(...t){let i=t.filter(e=>a(n(e),r).value===void 0);if(i.length>0)throw new e(305,`Missing required environment variables: ${i.join(`, `)}.`)}require(...e){t.require(...e)}static has(t){try{return a(n(t),r).value!==void 0}catch(t){if(t instanceof e&&t.code===305)return!1;throw t}}has(e){return t.has(e)}};export{o as Envapter,t as Environment};
 //# sourceMappingURL=Envapter.mjs.map