envapt 5.1.1 → 5.2.0-next.1

package/dist/node/Validators.mjs.map

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

package/dist/node/config.cjs

@@ -0,0 +1,2 @@
+const e=require("./NodeEnvapter.cjs");e.NodeEnvapter.syncProcessEnv=!0,e.NodeEnvapter.load();
+//# sourceMappingURL=config.cjs.map

package/dist/node/config.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.cjs","names":["Envapter"],"sources":["../../src/config.ts"],"sourcesContent":["import { Envapter } from '.';\n\n// Side-effect entry (`import 'envapt/config'`, `node --import envapt/config`, `-r envapt/config` for CJS):\n// a drop-in for `dotenv/config` that mirrors the loaded cascade into `process.env`. Importing Envapter\n// evaluates NodeEnvapter, whose static block binds the default source before load() runs.\nEnvapter.syncProcessEnv = true;\nEnvapter.load();\n"],"mappings":"sCAKA,EAAA,aAAS,eAAiB,GAC1BA,EAAAA,aAAS,KAAK"}

package/dist/node/config.mjs

@@ -0,0 +1,2 @@
+import{NodeEnvapter as e}from"./NodeEnvapter.mjs";e.syncProcessEnv=!0,e.load();export{};
+//# sourceMappingURL=config.mjs.map

package/dist/node/config.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.mjs","names":["Envapter"],"sources":["../../src/config.ts"],"sourcesContent":["import { Envapter } from '.';\n\n// Side-effect entry (`import 'envapt/config'`, `node --import envapt/config`, `-r envapt/config` for CJS):\n// a drop-in for `dotenv/config` that mirrors the loaded cascade into `process.env`. Importing Envapter\n// evaluates NodeEnvapter, whose static block binds the default source before load() runs.\nEnvapter.syncProcessEnv = true;\nEnvapter.load();\n"],"mappings":"kDAKA,EAAS,eAAiB,GAC1BA,EAAS,KAAK"}

package/dist/node/converters/BuiltInConverters.cjs

@@ -0,0 +1,2 @@
+const e=require("../Error.cjs"),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`);function c(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`]}var l=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=Number.parseInt(e,10);return Number.isNaN(n)?t:n}static float(e,t){let n=Number.parseFloat(e);return Number.isNaN(n)?t:n}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=c(t);if(r!==void 0)return r;if(typeof n==`number`)return n;if(typeof n==`string`){let t=c(n,!0);if(t===void 0)throw new e.EnvaptError(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 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.EnvaptError(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.EnvaptError(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.EnvaptError(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}[e]}};exports.BuiltInConverters=l;
+//# sourceMappingURL=BuiltInConverters.cjs.map

package/dist/node/converters/BuiltInConverters.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"BuiltInConverters.cjs","names":["EnvaptError","converter"],"sources":["../../../src/converters/BuiltInConverters.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/unbound-method */\n\nimport { EnvaptError, EnvaptErrorCodes } from '../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/**\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/**\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 = Number.parseInt(raw, 10);\n        return Number.isNaN(parsed) ? fallback : parsed;\n    }\n\n    static float(raw: string, fallback?: number): number | undefined {\n        const parsed = Number.parseFloat(raw);\n        return Number.isNaN(parsed) ? fallback : parsed;\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    /**\n     * Process the raw env value for an {@link ArrayOf} configuration.\n     *\n     * Behaviour:\n     * - Splits on `config.delimiter`, trims each item, and filters out empty entries.\n     * - With a scalar element token: runs each item through the matching built-in converter.\n     *   If any element returns `undefined`, throws `ArrayElementConversionFailed` with positional info.\n     * - With a custom function element: runs each item through the function. Propagates user\n     *   exceptions; treats `undefined` returns as conversion failures (same throw as scalar path).\n     * - Returns `[]` when the raw value is empty/whitespace.\n     * - When `strict` is true, throws `EmptyArrayElement` on any empty/whitespace item instead\n     *   of silently filtering it out.\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        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        } as const;\n\n        return converters[type];\n    }\n}\n"],"mappings":"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"}

package/dist/node/converters/BuiltInConverters.mjs

@@ -0,0 +1,2 @@
+import{EnvaptError as e}from"../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`);function c(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`]}var l=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=Number.parseInt(e,10);return Number.isNaN(n)?t:n}static float(e,t){let n=Number.parseFloat(e);return Number.isNaN(n)?t:n}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=c(t);if(r!==void 0)return r;if(typeof n==`number`)return n;if(typeof n==`string`){let t=c(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 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}[e]}};export{l as BuiltInConverters};
+//# sourceMappingURL=BuiltInConverters.mjs.map

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

@@ -0,0 +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 '../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/**\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/**\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 = Number.parseInt(raw, 10);\n        return Number.isNaN(parsed) ? fallback : parsed;\n    }\n\n    static float(raw: string, fallback?: number): number | undefined {\n        const parsed = Number.parseFloat(raw);\n        return Number.isNaN(parsed) ? fallback : parsed;\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    /**\n     * Process the raw env value for an {@link ArrayOf} configuration.\n     *\n     * Behaviour:\n     * - Splits on `config.delimiter`, trims each item, and filters out empty entries.\n     * - With a scalar element token: runs each item through the matching built-in converter.\n     *   If any element returns `undefined`, throws `ArrayElementConversionFailed` with positional info.\n     * - With a custom function element: runs each item through the function. Propagates user\n     *   exceptions; treats `undefined` returns as conversion failures (same throw as scalar path).\n     * - Returns `[]` when the raw value is empty/whitespace.\n     * - When `strict` is true, throws `EmptyArrayElement` on any empty/whitespace item instead\n     *   of silently filtering it out.\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        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        } as const;\n\n        return converters[type];\n    }\n}\n"],"mappings":"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"}

package/dist/node/converters/Converters.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Converters.cjs","names":[],"sources":["../../../src/converters/Converters.ts"],"sourcesContent":["const SCALAR = {\n    String: 'string',\n    Number: 'number',\n    Boolean: 'boolean',\n    Bigint: 'bigint',\n    Symbol: 'symbol',\n    Integer: 'integer',\n    Float: 'float',\n    Json: 'json',\n    Url: 'url',\n    Regexp: 'regexp',\n    Date: 'date',\n    Time: 'time'\n} as const;\n\n/**\n * String tokens for every built-in scalar converter.\n * @public\n */\nexport type ConverterToken = (typeof SCALAR)[keyof typeof SCALAR];\n\n/**\n * Custom element converter for use inside {@link Converters.array}. Receives the trimmed,\n * non-empty raw string for one array slot and returns the parsed value.\n * @public\n */\nexport type CustomElementConverter<TReturn = unknown> = (raw: string) => TReturn;\n\n/**\n * Valid element converters for {@link Converters.array}: any scalar token except\n * `json` and `regexp` (those don't compose as array elements), or a custom function.\n * @public\n */\nexport type ArrayElement = Exclude<ConverterToken, 'json' | 'regexp'> | CustomElementConverter;\n\n/**\n * Phantom-branded token produced by {@link Converters.array}. The `T` type parameter carries\n * the element converter through any variable indirection so inference survives. The\n * `__envaptKind` discriminant is present at runtime for dispatch.\n * @public\n */\nexport interface ArrayOf<TElement extends ArrayElement = ArrayElement> {\n    readonly __envaptKind: 'array';\n    readonly of: TElement;\n    readonly delimiter: string;\n}\n\n/**\n * Runtime type guard for tokens produced by {@link Converters.array}.\n * @internal\n */\nexport function isArrayOf(value: unknown): value is ArrayOf {\n    return typeof value === 'object' && value !== null && '__envaptKind' in value && value.__envaptKind === 'array';\n}\n\ntype ArrayScalarElement = Exclude<ConverterToken, 'json' | 'regexp'>;\n\n// Overloads. The function-element overload must come first so it wins inference when `of`\n// is a function, otherwise TS picks the scalar branch and `raw` defaults to `any`.\nfunction buildArrayConverter<TReturn>(opts: {\n    of: CustomElementConverter<TReturn>;\n    delimiter?: string;\n}): ArrayOf<CustomElementConverter<TReturn>>;\nfunction buildArrayConverter<TToken extends ArrayScalarElement>(opts: {\n    of: TToken;\n    delimiter?: string;\n}): ArrayOf<TToken>;\nfunction buildArrayConverter(opts?: { delimiter?: string }): ArrayOf<'string'>;\nfunction buildArrayConverter(opts?: { of?: ArrayElement; delimiter?: string }): ArrayOf<ArrayElement> {\n    return {\n        __envaptKind: 'array',\n        of: opts?.of ?? SCALAR.String,\n        delimiter: opts?.delimiter ?? ','\n    };\n}\n\n/**\n * Built-in converters for environment variables. Use the scalar tokens (e.g. `Converters.Number`)\n * for primitive types and the {@link Converters.array} builder for delimited lists.\n *\n * @example\n * ```ts\n * \\@Envapt('PORT', { converter: Converters.Number, fallback: 3000 })\n * static readonly port: number;\n *\n * \\@Envapt('TAGS', { converter: Converters.array({ of: Converters.String, delimiter: ' ' }) })\n * static readonly tags: string[];\n * ```\n *\n * @public\n */\nexport const Converters = {\n    ...SCALAR,\n    array: buildArrayConverter\n} as const;\n"],"mappings":"AAAA,MAAM,EAAS,CACX,OAAQ,SACR,OAAQ,SACR,QAAS,UACT,OAAQ,SACR,OAAQ,SACR,QAAS,UACT,MAAO,QACP,KAAM,OACN,IAAK,MACL,OAAQ,SACR,KAAM,OACN,KAAM,MACV,EAsCA,SAAgB,EAAU,EAAkC,CACxD,OAAO,OAAO,GAAU,YAAY,GAAkB,iBAAkB,GAAS,EAAM,eAAiB,OAC5G,CAeA,SAAS,EAAoB,EAAyE,CAClG,MAAO,CACH,aAAc,QACd,GAAI,GAAM,IAAM,EAAO,OACvB,UAAW,GAAM,WAAa,GAClC,CACJ,CAiBA,MAAa,EAAa,CACtB,GAAG,EACH,MAAO,CACX"}

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

@@ -0,0 +1,93 @@
+//#region src/converters/Converters.d.ts
+declare const SCALAR: {
+  readonly String: "string";
+  readonly Number: "number";
+  readonly Boolean: "boolean";
+  readonly Bigint: "bigint";
+  readonly Symbol: "symbol";
+  readonly Integer: "integer";
+  readonly Float: "float";
+  readonly Json: "json";
+  readonly Url: "url";
+  readonly Regexp: "regexp";
+  readonly Date: "date";
+  readonly Time: "time";
+};
+/**
+ * String tokens for every built-in scalar converter.
+ * @public
+ */
+type ConverterToken = (typeof SCALAR)[keyof typeof SCALAR];
+/**
+ * Custom element converter for use inside {@link Converters.array}. Receives the trimmed,
+ * non-empty raw string for one array slot and returns the parsed value.
+ * @public
+ */
+type CustomElementConverter<TReturn = unknown> = (raw: string) => TReturn;
+/**
+ * Valid element converters for {@link Converters.array}: any scalar token except
+ * `json` and `regexp` (those don't compose as array elements), or a custom function.
+ * @public
+ */
+type ArrayElement = Exclude<ConverterToken, 'json' | 'regexp'> | CustomElementConverter;
+/**
+ * Phantom-branded token produced by {@link Converters.array}. The `T` type parameter carries
+ * the element converter through any variable indirection so inference survives. The
+ * `__envaptKind` discriminant is present at runtime for dispatch.
+ * @public
+ */
+interface ArrayOf<TElement extends ArrayElement = ArrayElement> {
+  readonly __envaptKind: 'array';
+  readonly of: TElement;
+  readonly delimiter: string;
+}
+/**
+ * Runtime type guard for tokens produced by {@link Converters.array}.
+ * @internal
+ */
+declare function isArrayOf(value: unknown): value is ArrayOf;
+type ArrayScalarElement = Exclude<ConverterToken, 'json' | 'regexp'>;
+declare function buildArrayConverter<TReturn>(opts: {
+  of: CustomElementConverter<TReturn>;
+  delimiter?: string;
+}): ArrayOf<CustomElementConverter<TReturn>>;
+declare function buildArrayConverter<TToken extends ArrayScalarElement>(opts: {
+  of: TToken;
+  delimiter?: string;
+}): ArrayOf<TToken>;
+declare function buildArrayConverter(opts?: {
+  delimiter?: string;
+}): ArrayOf<'string'>;
+/**
+ * Built-in converters for environment variables. Use the scalar tokens (e.g. `Converters.Number`)
+ * for primitive types and the {@link Converters.array} builder for delimited lists.
+ *
+ * @example
+ * ```ts
+ * \@Envapt('PORT', { converter: Converters.Number, fallback: 3000 })
+ * static readonly port: number;
+ *
+ * \@Envapt('TAGS', { converter: Converters.array({ of: Converters.String, delimiter: ' ' }) })
+ * static readonly tags: string[];
+ * ```
+ *
+ * @public
+ */
+declare const Converters: {
+  readonly array: typeof buildArrayConverter;
+  readonly String: "string";
+  readonly Number: "number";
+  readonly Boolean: "boolean";
+  readonly Bigint: "bigint";
+  readonly Symbol: "symbol";
+  readonly Integer: "integer";
+  readonly Float: "float";
+  readonly Json: "json";
+  readonly Url: "url";
+  readonly Regexp: "regexp";
+  readonly Date: "date";
+  readonly Time: "time";
+};
+//#endregion
+export { ArrayElement, ArrayOf, ConverterToken, Converters, CustomElementConverter, isArrayOf };
+//# sourceMappingURL=Converters.d.mts.map

package/dist/node/converters/Converters.mjs

@@ -0,0 +1,2 @@
+const e={String:`string`,Number:`number`,Boolean:`boolean`,Bigint:`bigint`,Symbol:`symbol`,Integer:`integer`,Float:`float`,Json:`json`,Url:`url`,Regexp:`regexp`,Date:`date`,Time:`time`};function t(e){return typeof e==`object`&&!!e&&`__envaptKind`in e&&e.__envaptKind===`array`}function n(t){return{__envaptKind:`array`,of:t?.of??e.String,delimiter:t?.delimiter??`,`}}const r={...e,array:n};export{r as Converters,t as isArrayOf};
+//# sourceMappingURL=Converters.mjs.map

package/dist/node/converters/Converters.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Converters.mjs","names":[],"sources":["../../../src/converters/Converters.ts"],"sourcesContent":["const SCALAR = {\n    String: 'string',\n    Number: 'number',\n    Boolean: 'boolean',\n    Bigint: 'bigint',\n    Symbol: 'symbol',\n    Integer: 'integer',\n    Float: 'float',\n    Json: 'json',\n    Url: 'url',\n    Regexp: 'regexp',\n    Date: 'date',\n    Time: 'time'\n} as const;\n\n/**\n * String tokens for every built-in scalar converter.\n * @public\n */\nexport type ConverterToken = (typeof SCALAR)[keyof typeof SCALAR];\n\n/**\n * Custom element converter for use inside {@link Converters.array}. Receives the trimmed,\n * non-empty raw string for one array slot and returns the parsed value.\n * @public\n */\nexport type CustomElementConverter<TReturn = unknown> = (raw: string) => TReturn;\n\n/**\n * Valid element converters for {@link Converters.array}: any scalar token except\n * `json` and `regexp` (those don't compose as array elements), or a custom function.\n * @public\n */\nexport type ArrayElement = Exclude<ConverterToken, 'json' | 'regexp'> | CustomElementConverter;\n\n/**\n * Phantom-branded token produced by {@link Converters.array}. The `T` type parameter carries\n * the element converter through any variable indirection so inference survives. The\n * `__envaptKind` discriminant is present at runtime for dispatch.\n * @public\n */\nexport interface ArrayOf<TElement extends ArrayElement = ArrayElement> {\n    readonly __envaptKind: 'array';\n    readonly of: TElement;\n    readonly delimiter: string;\n}\n\n/**\n * Runtime type guard for tokens produced by {@link Converters.array}.\n * @internal\n */\nexport function isArrayOf(value: unknown): value is ArrayOf {\n    return typeof value === 'object' && value !== null && '__envaptKind' in value && value.__envaptKind === 'array';\n}\n\ntype ArrayScalarElement = Exclude<ConverterToken, 'json' | 'regexp'>;\n\n// Overloads. The function-element overload must come first so it wins inference when `of`\n// is a function, otherwise TS picks the scalar branch and `raw` defaults to `any`.\nfunction buildArrayConverter<TReturn>(opts: {\n    of: CustomElementConverter<TReturn>;\n    delimiter?: string;\n}): ArrayOf<CustomElementConverter<TReturn>>;\nfunction buildArrayConverter<TToken extends ArrayScalarElement>(opts: {\n    of: TToken;\n    delimiter?: string;\n}): ArrayOf<TToken>;\nfunction buildArrayConverter(opts?: { delimiter?: string }): ArrayOf<'string'>;\nfunction buildArrayConverter(opts?: { of?: ArrayElement; delimiter?: string }): ArrayOf<ArrayElement> {\n    return {\n        __envaptKind: 'array',\n        of: opts?.of ?? SCALAR.String,\n        delimiter: opts?.delimiter ?? ','\n    };\n}\n\n/**\n * Built-in converters for environment variables. Use the scalar tokens (e.g. `Converters.Number`)\n * for primitive types and the {@link Converters.array} builder for delimited lists.\n *\n * @example\n * ```ts\n * \\@Envapt('PORT', { converter: Converters.Number, fallback: 3000 })\n * static readonly port: number;\n *\n * \\@Envapt('TAGS', { converter: Converters.array({ of: Converters.String, delimiter: ' ' }) })\n * static readonly tags: string[];\n * ```\n *\n * @public\n */\nexport const Converters = {\n    ...SCALAR,\n    array: buildArrayConverter\n} as const;\n"],"mappings":"AAAA,MAAM,EAAS,CACX,OAAQ,SACR,OAAQ,SACR,QAAS,UACT,OAAQ,SACR,OAAQ,SACR,QAAS,UACT,MAAO,QACP,KAAM,OACN,IAAK,MACL,OAAQ,SACR,KAAM,OACN,KAAM,MACV,EAsCA,SAAgB,EAAU,EAAkC,CACxD,OAAO,OAAO,GAAU,YAAY,GAAkB,iBAAkB,GAAS,EAAM,eAAiB,OAC5G,CAeA,SAAS,EAAoB,EAAyE,CAClG,MAAO,CACH,aAAc,QACd,GAAI,GAAM,IAAM,EAAO,OACvB,UAAW,GAAM,WAAa,GAClC,CACJ,CAiBA,MAAa,EAAa,CACtB,GAAG,EACH,MAAO,CACX"}

package/dist/node/converters/ListOfBuiltInConverters.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ListOfBuiltInConverters.cjs","names":[],"sources":["../../../src/converters/ListOfBuiltInConverters.ts"],"sourcesContent":["import type { ConverterToken } from './Converters';\nimport type { JsonValue } from '../types';\n\n/**\n * List of built-in scalar converters for Envapt. Arrays are handled separately via\n * the {@link Converters.array} builder and the `ArrayOf<...>` brand.\n * @internal\n */\nexport const ListOfBuiltInConverters: ConverterToken[] = [\n    'string',\n    'number',\n    'boolean',\n    'bigint',\n    'symbol',\n    'integer',\n    'float',\n    'json',\n    'url',\n    'regexp',\n    'date',\n    'time'\n] as const;\n\n/**\n * Type checking functions for built-in scalar converter return types.\n * @internal\n */\nexport const BuiltInConverterTypeCheckers: Record<ConverterToken, (value: unknown) => boolean> = {\n    string: (value: unknown): value is string => typeof value === 'string',\n    number: (value: unknown): value is number => typeof value === 'number',\n    boolean: (value: unknown): value is boolean => typeof value === 'boolean',\n    bigint: (value: unknown): value is bigint => typeof value === 'bigint',\n    symbol: (value: unknown): value is symbol => typeof value === 'symbol',\n    integer: (value: unknown): value is number => typeof value === 'number' && Number.isInteger(value),\n    float: (value: unknown): value is number => typeof value === 'number',\n    json: (value: unknown): value is JsonValue => {\n        try {\n            JSON.parse(JSON.stringify(value));\n            return true;\n        } catch {\n            return false;\n        }\n    },\n    url: (value: unknown): value is URL => value instanceof URL,\n    regexp: (value: unknown): value is RegExp => value instanceof RegExp,\n    date: (value: unknown): value is Date => value instanceof Date,\n    time: (value: unknown): value is number | string => typeof value === 'number' || typeof value === 'string'\n};\n"],"mappings":"AAQA,MAAa,EAA4C,CACrD,SACA,SACA,UACA,SACA,SACA,UACA,QACA,OACA,MACA,SACA,OACA,MACJ,EAMa,EAAoF,CAC7F,OAAS,GAAoC,OAAO,GAAU,SAC9D,OAAS,GAAoC,OAAO,GAAU,SAC9D,QAAU,GAAqC,OAAO,GAAU,UAChE,OAAS,GAAoC,OAAO,GAAU,SAC9D,OAAS,GAAoC,OAAO,GAAU,SAC9D,QAAU,GAAoC,OAAO,GAAU,UAAY,OAAO,UAAU,CAAK,EACjG,MAAQ,GAAoC,OAAO,GAAU,SAC7D,KAAO,GAAuC,CAC1C,GAAI,CAEA,OADA,KAAK,MAAM,KAAK,UAAU,CAAK,CAAC,EACzB,EACX,MAAQ,CACJ,MAAO,EACX,CACJ,EACA,IAAM,GAAiC,aAAiB,IACxD,OAAS,GAAoC,aAAiB,OAC9D,KAAO,GAAkC,aAAiB,KAC1D,KAAO,GAA6C,OAAO,GAAU,UAAY,OAAO,GAAU,QACtG"}

package/dist/node/converters/ListOfBuiltInConverters.mjs

@@ -0,0 +1,2 @@
+const e=[`string`,`number`,`boolean`,`bigint`,`symbol`,`integer`,`float`,`json`,`url`,`regexp`,`date`,`time`],t={string:e=>typeof e==`string`,number:e=>typeof e==`number`,boolean:e=>typeof e==`boolean`,bigint:e=>typeof e==`bigint`,symbol:e=>typeof e==`symbol`,integer:e=>typeof e==`number`&&Number.isInteger(e),float:e=>typeof e==`number`,json:e=>{try{return JSON.parse(JSON.stringify(e)),!0}catch{return!1}},url:e=>e instanceof URL,regexp:e=>e instanceof RegExp,date:e=>e instanceof Date,time:e=>typeof e==`number`||typeof e==`string`};export{t as BuiltInConverterTypeCheckers,e as ListOfBuiltInConverters};
+//# sourceMappingURL=ListOfBuiltInConverters.mjs.map

package/dist/node/converters/ListOfBuiltInConverters.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ListOfBuiltInConverters.mjs","names":[],"sources":["../../../src/converters/ListOfBuiltInConverters.ts"],"sourcesContent":["import type { ConverterToken } from './Converters';\nimport type { JsonValue } from '../types';\n\n/**\n * List of built-in scalar converters for Envapt. Arrays are handled separately via\n * the {@link Converters.array} builder and the `ArrayOf<...>` brand.\n * @internal\n */\nexport const ListOfBuiltInConverters: ConverterToken[] = [\n    'string',\n    'number',\n    'boolean',\n    'bigint',\n    'symbol',\n    'integer',\n    'float',\n    'json',\n    'url',\n    'regexp',\n    'date',\n    'time'\n] as const;\n\n/**\n * Type checking functions for built-in scalar converter return types.\n * @internal\n */\nexport const BuiltInConverterTypeCheckers: Record<ConverterToken, (value: unknown) => boolean> = {\n    string: (value: unknown): value is string => typeof value === 'string',\n    number: (value: unknown): value is number => typeof value === 'number',\n    boolean: (value: unknown): value is boolean => typeof value === 'boolean',\n    bigint: (value: unknown): value is bigint => typeof value === 'bigint',\n    symbol: (value: unknown): value is symbol => typeof value === 'symbol',\n    integer: (value: unknown): value is number => typeof value === 'number' && Number.isInteger(value),\n    float: (value: unknown): value is number => typeof value === 'number',\n    json: (value: unknown): value is JsonValue => {\n        try {\n            JSON.parse(JSON.stringify(value));\n            return true;\n        } catch {\n            return false;\n        }\n    },\n    url: (value: unknown): value is URL => value instanceof URL,\n    regexp: (value: unknown): value is RegExp => value instanceof RegExp,\n    date: (value: unknown): value is Date => value instanceof Date,\n    time: (value: unknown): value is number | string => typeof value === 'number' || typeof value === 'string'\n};\n"],"mappings":"AAQA,MAAa,EAA4C,CACrD,SACA,SACA,UACA,SACA,SACA,UACA,QACA,OACA,MACA,SACA,OACA,MACJ,EAMa,EAAoF,CAC7F,OAAS,GAAoC,OAAO,GAAU,SAC9D,OAAS,GAAoC,OAAO,GAAU,SAC9D,QAAU,GAAqC,OAAO,GAAU,UAChE,OAAS,GAAoC,OAAO,GAAU,SAC9D,OAAS,GAAoC,OAAO,GAAU,SAC9D,QAAU,GAAoC,OAAO,GAAU,UAAY,OAAO,UAAU,CAAK,EACjG,MAAQ,GAAoC,OAAO,GAAU,SAC7D,KAAO,GAAuC,CAC1C,GAAI,CAEA,OADA,KAAK,MAAM,KAAK,UAAU,CAAK,CAAC,EACzB,EACX,MAAQ,CACJ,MAAO,EACX,CACJ,EACA,IAAM,GAAiC,aAAiB,IACxD,OAAS,GAAoC,aAAiB,OAC9D,KAAO,GAAkC,aAAiB,KAC1D,KAAO,GAA6C,OAAO,GAAU,UAAY,OAAO,GAAU,QACtG"}

package/dist/node/converters/ValueConverter.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ValueConverter.cjs","names":["Validator","EnvaptError","BuiltInConverters"],"sources":["../../../src/converters/ValueConverter.ts"],"sourcesContent":["import { BuiltInConverters } from './BuiltInConverters';\nimport { EnvaptError, EnvaptErrorCodes } from '../Error';\nimport { Validator } from '../Validators';\n\nimport type { ArrayOf } from './Converters';\nimport type { StandardSchemaV1 } from '../StandardSchema';\nimport type { BuiltInConverter, EnvKeyInput, EnvaptConverter, PrimitiveConstructor } from '../types';\nimport type { EnvapterService } from '../types/Env';\n\nfunction formatKeyForError(key: EnvKeyInput): string {\n    return Array.isArray(key) ? `[${key.join(', ')}]` : String(key);\n}\n\n/**\n * Convert a resolved environment value to its declared type via built-in, primitive, array,\n * custom, or Standard Schema converters.\n * @internal\n */\nexport class ValueConverter {\n    constructor(private readonly envService: EnvapterService) {}\n\n    convertValue<TFallback>(\n        key: EnvKeyInput,\n        fallback: TFallback | undefined,\n        converter: EnvaptConverter<TFallback> | undefined,\n        hasFallback: boolean\n    ): TFallback | null | undefined {\n        const resolvedConverter = this.resolveConverter(converter, fallback);\n        const processedFallback = this.processFallbackForConverter(resolvedConverter, fallback);\n\n        if (Validator.isArrayConverter(resolvedConverter)) {\n            return this.processArrayConverter(key, processedFallback, resolvedConverter, hasFallback);\n        }\n\n        if (Validator.isPrimitiveConstructor(resolvedConverter)) {\n            const stringConverter = this.convertPrimitiveToString(resolvedConverter);\n            return this.processBuiltInConverter(key, processedFallback, stringConverter, hasFallback, true);\n        }\n\n        if (Validator.isBuiltInConverter(resolvedConverter)) {\n            return this.processBuiltInConverter(key, processedFallback, resolvedConverter, hasFallback, false);\n        }\n\n        return this.processCustomConverter(key, processedFallback, resolvedConverter, hasFallback);\n    }\n\n    private processFallbackForConverter<TFallback>(\n        converter: EnvaptConverter<TFallback>,\n        fallback: TFallback | undefined\n    ): TFallback | undefined {\n        if (Validator.isPrimitiveConstructor(converter) && fallback !== undefined) {\n            return Validator.coercePrimitiveFallback<TFallback>(converter, fallback);\n        }\n        return fallback;\n    }\n\n    private convertPrimitiveToString(primitiveConstructor: PrimitiveConstructor): BuiltInConverter {\n        if (primitiveConstructor === String) return 'string';\n        if (primitiveConstructor === Number) return 'number';\n        if (primitiveConstructor === Boolean) return 'boolean';\n        if (primitiveConstructor === BigInt) return 'bigint';\n        /* v8 ignore next -- @preserve */\n        if (primitiveConstructor === Symbol) return 'symbol';\n\n        /* v8 ignore next -- @preserve */\n        throw new EnvaptError(EnvaptErrorCodes.InvalidConverterType, `Unknown primitive constructor`);\n    }\n\n    private processBuiltInConverter<TFallback>(\n        key: EnvKeyInput,\n        fallback: TFallback | undefined,\n        resolvedConverter: BuiltInConverter,\n        hasFallback: boolean,\n        wasOriginallyConstructor: boolean\n    ): TFallback | null | undefined {\n        Validator.builtInConverter(resolvedConverter);\n\n        if (hasFallback && fallback !== undefined && !wasOriginallyConstructor) {\n            Validator.validateBuiltInConverterFallback(resolvedConverter, fallback);\n        }\n\n        const parsed = this.envService.get(key, undefined);\n\n        if (parsed === undefined) {\n            if (!hasFallback) return null;\n            // For converters with asymmetric fallback / return types — currently only `time`,\n            // whose fallback may be a string while the return type is `number` — route the\n            // fallback through the converter so it gets coerced to the return type.\n            if (resolvedConverter === 'time' && typeof fallback === 'string') {\n                const timeFn = BuiltInConverters.getConverter(resolvedConverter);\n                return timeFn('', fallback) as TFallback;\n            }\n            return fallback;\n        }\n\n        const converterFn = BuiltInConverters.getConverter(resolvedConverter);\n        const result = converterFn(parsed, fallback);\n\n        if (result === undefined && !hasFallback) return null;\n\n        return result as TFallback;\n    }\n\n    private processArrayConverter<TFallback>(\n        key: EnvKeyInput,\n        fallback: TFallback | undefined,\n        resolvedConverter: ArrayOf,\n        hasFallback: boolean\n    ): TFallback | null | undefined {\n        Validator.arrayConverter(resolvedConverter);\n\n        if (hasFallback && fallback !== undefined && !Array.isArray(fallback)) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidFallback,\n                `ArrayOf<...> requires that the fallback be an array, got ${typeof fallback}`\n            );\n        }\n\n        if (hasFallback && Array.isArray(fallback)) {\n            Validator.validateArrayFallbackElementTypes(fallback);\n            Validator.validateArrayConverterElementTypeMatch(resolvedConverter.of, fallback);\n        }\n\n        const parsed = this.envService.get(key, undefined);\n\n        if (parsed === undefined) {\n            if (!hasFallback) return null;\n            // When the array element is `time` and the fallback is a list of time-strings,\n            // coerce each entry through the time converter so the returned array is\n            // `number[]` matching the declared return type.\n            if (\n                resolvedConverter.of === 'time' &&\n                Array.isArray(fallback) &&\n                fallback.every((v) => typeof v === 'string')\n            ) {\n                const timeFn = BuiltInConverters.getConverter('time');\n                return fallback.map((v) => timeFn('', v as string)) as TFallback;\n            }\n            return fallback;\n        }\n\n        const result = BuiltInConverters.processArrayConverter(parsed, resolvedConverter, this.envService.isStrict());\n        return result as TFallback;\n    }\n\n    private processCustomConverter<TFallback>(\n        key: EnvKeyInput,\n        fallback: TFallback | undefined,\n        resolvedConverter: EnvaptConverter<TFallback>,\n        _hasFallback: boolean // hasFallback is not needed because customConverter is called even if the raw value is undefined\n    ): TFallback | null | undefined {\n        Validator.customConvertor(resolvedConverter);\n\n        const raw = this.envService.get(key, undefined);\n\n        return resolvedConverter(raw, fallback);\n    }\n\n    private resolveConverter<TFallback>(\n        converter: EnvaptConverter<TFallback> | undefined,\n        fallback: TFallback | undefined\n    ): EnvaptConverter<TFallback> {\n        if (converter) return converter;\n\n        const fallbackType = typeof fallback;\n        if (fallbackType === 'number') return 'number';\n        if (fallbackType === 'boolean') return 'boolean';\n        if (fallbackType === 'bigint') return 'bigint';\n        if (fallbackType === 'symbol') return 'symbol';\n        return 'string';\n    }\n\n    // Single dispatch site for decorator + `Envapter.parse()` so error codes (208 / 209 / 305)\n    // stay consistent. Missing+no-fallback throws here so callers don't duplicate the check.\n    convertWithSchema(key: EnvKeyInput, schema: StandardSchemaV1, fallback: unknown, hasFallback: boolean): unknown {\n        const raw = this.envService.get(key, undefined);\n\n        if (raw === undefined) {\n            if (hasFallback) return fallback;\n            throw new EnvaptError(\n                EnvaptErrorCodes.MissingEnvValue,\n                `Required environment variable \"${formatKeyForError(key)}\" is missing or empty.`\n            );\n        }\n\n        let outcome: StandardSchemaV1.Result<unknown> | Promise<StandardSchemaV1.Result<unknown>>;\n        try {\n            outcome = schema['~standard'].validate(raw);\n        } catch (cause) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.SchemaThrew,\n                `Schema for \"${formatKeyForError(key)}\" threw during validation: ${(cause as Error).message}`,\n                { cause }\n            );\n        }\n\n        if (outcome instanceof Promise) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidUserDefinedConfig,\n                `Schema for \"${formatKeyForError(key)}\" returned a Promise. envapt requires synchronous schemas; use a sync validator or perform async checks outside the env layer.`\n            );\n        }\n\n        if (outcome.issues !== undefined) {\n            const first = outcome.issues[0];\n            const firstMessage = first?.message ?? 'no issue message';\n            throw new EnvaptError(\n                EnvaptErrorCodes.SchemaValidationFailed,\n                `Schema validation failed for \"${formatKeyForError(key)}\": ${firstMessage}`,\n                { issues: outcome.issues }\n            );\n        }\n\n        return outcome.value;\n    }\n}\n"],"mappings":"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"}

package/dist/node/converters/ValueConverter.d.mts

@@ -0,0 +1,25 @@
+import { EnvaptConverter } from "../types/Conversion.mjs";
+import { StandardSchemaV1 } from "../StandardSchema.mjs";
+import { EnvKeyInput, EnvapterService } from "../types/Env.mjs";
+
+//#region src/converters/ValueConverter.d.ts
+/**
+ * Convert a resolved environment value to its declared type via built-in, primitive, array,
+ * custom, or Standard Schema converters.
+ * @internal
+ */
+declare class ValueConverter {
+  private readonly envService;
+  constructor(envService: EnvapterService);
+  convertValue<TFallback>(key: EnvKeyInput, fallback: TFallback | undefined, converter: EnvaptConverter<TFallback> | undefined, hasFallback: boolean): TFallback | null | undefined;
+  private processFallbackForConverter;
+  private convertPrimitiveToString;
+  private processBuiltInConverter;
+  private processArrayConverter;
+  private processCustomConverter;
+  private resolveConverter;
+  convertWithSchema(key: EnvKeyInput, schema: StandardSchemaV1, fallback: unknown, hasFallback: boolean): unknown;
+}
+//#endregion
+export { ValueConverter };
+//# sourceMappingURL=ValueConverter.d.mts.map

package/dist/node/converters/ValueConverter.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ValueConverter.mjs","names":[],"sources":["../../../src/converters/ValueConverter.ts"],"sourcesContent":["import { BuiltInConverters } from './BuiltInConverters';\nimport { EnvaptError, EnvaptErrorCodes } from '../Error';\nimport { Validator } from '../Validators';\n\nimport type { ArrayOf } from './Converters';\nimport type { StandardSchemaV1 } from '../StandardSchema';\nimport type { BuiltInConverter, EnvKeyInput, EnvaptConverter, PrimitiveConstructor } from '../types';\nimport type { EnvapterService } from '../types/Env';\n\nfunction formatKeyForError(key: EnvKeyInput): string {\n    return Array.isArray(key) ? `[${key.join(', ')}]` : String(key);\n}\n\n/**\n * Convert a resolved environment value to its declared type via built-in, primitive, array,\n * custom, or Standard Schema converters.\n * @internal\n */\nexport class ValueConverter {\n    constructor(private readonly envService: EnvapterService) {}\n\n    convertValue<TFallback>(\n        key: EnvKeyInput,\n        fallback: TFallback | undefined,\n        converter: EnvaptConverter<TFallback> | undefined,\n        hasFallback: boolean\n    ): TFallback | null | undefined {\n        const resolvedConverter = this.resolveConverter(converter, fallback);\n        const processedFallback = this.processFallbackForConverter(resolvedConverter, fallback);\n\n        if (Validator.isArrayConverter(resolvedConverter)) {\n            return this.processArrayConverter(key, processedFallback, resolvedConverter, hasFallback);\n        }\n\n        if (Validator.isPrimitiveConstructor(resolvedConverter)) {\n            const stringConverter = this.convertPrimitiveToString(resolvedConverter);\n            return this.processBuiltInConverter(key, processedFallback, stringConverter, hasFallback, true);\n        }\n\n        if (Validator.isBuiltInConverter(resolvedConverter)) {\n            return this.processBuiltInConverter(key, processedFallback, resolvedConverter, hasFallback, false);\n        }\n\n        return this.processCustomConverter(key, processedFallback, resolvedConverter, hasFallback);\n    }\n\n    private processFallbackForConverter<TFallback>(\n        converter: EnvaptConverter<TFallback>,\n        fallback: TFallback | undefined\n    ): TFallback | undefined {\n        if (Validator.isPrimitiveConstructor(converter) && fallback !== undefined) {\n            return Validator.coercePrimitiveFallback<TFallback>(converter, fallback);\n        }\n        return fallback;\n    }\n\n    private convertPrimitiveToString(primitiveConstructor: PrimitiveConstructor): BuiltInConverter {\n        if (primitiveConstructor === String) return 'string';\n        if (primitiveConstructor === Number) return 'number';\n        if (primitiveConstructor === Boolean) return 'boolean';\n        if (primitiveConstructor === BigInt) return 'bigint';\n        /* v8 ignore next -- @preserve */\n        if (primitiveConstructor === Symbol) return 'symbol';\n\n        /* v8 ignore next -- @preserve */\n        throw new EnvaptError(EnvaptErrorCodes.InvalidConverterType, `Unknown primitive constructor`);\n    }\n\n    private processBuiltInConverter<TFallback>(\n        key: EnvKeyInput,\n        fallback: TFallback | undefined,\n        resolvedConverter: BuiltInConverter,\n        hasFallback: boolean,\n        wasOriginallyConstructor: boolean\n    ): TFallback | null | undefined {\n        Validator.builtInConverter(resolvedConverter);\n\n        if (hasFallback && fallback !== undefined && !wasOriginallyConstructor) {\n            Validator.validateBuiltInConverterFallback(resolvedConverter, fallback);\n        }\n\n        const parsed = this.envService.get(key, undefined);\n\n        if (parsed === undefined) {\n            if (!hasFallback) return null;\n            // For converters with asymmetric fallback / return types — currently only `time`,\n            // whose fallback may be a string while the return type is `number` — route the\n            // fallback through the converter so it gets coerced to the return type.\n            if (resolvedConverter === 'time' && typeof fallback === 'string') {\n                const timeFn = BuiltInConverters.getConverter(resolvedConverter);\n                return timeFn('', fallback) as TFallback;\n            }\n            return fallback;\n        }\n\n        const converterFn = BuiltInConverters.getConverter(resolvedConverter);\n        const result = converterFn(parsed, fallback);\n\n        if (result === undefined && !hasFallback) return null;\n\n        return result as TFallback;\n    }\n\n    private processArrayConverter<TFallback>(\n        key: EnvKeyInput,\n        fallback: TFallback | undefined,\n        resolvedConverter: ArrayOf,\n        hasFallback: boolean\n    ): TFallback | null | undefined {\n        Validator.arrayConverter(resolvedConverter);\n\n        if (hasFallback && fallback !== undefined && !Array.isArray(fallback)) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidFallback,\n                `ArrayOf<...> requires that the fallback be an array, got ${typeof fallback}`\n            );\n        }\n\n        if (hasFallback && Array.isArray(fallback)) {\n            Validator.validateArrayFallbackElementTypes(fallback);\n            Validator.validateArrayConverterElementTypeMatch(resolvedConverter.of, fallback);\n        }\n\n        const parsed = this.envService.get(key, undefined);\n\n        if (parsed === undefined) {\n            if (!hasFallback) return null;\n            // When the array element is `time` and the fallback is a list of time-strings,\n            // coerce each entry through the time converter so the returned array is\n            // `number[]` matching the declared return type.\n            if (\n                resolvedConverter.of === 'time' &&\n                Array.isArray(fallback) &&\n                fallback.every((v) => typeof v === 'string')\n            ) {\n                const timeFn = BuiltInConverters.getConverter('time');\n                return fallback.map((v) => timeFn('', v as string)) as TFallback;\n            }\n            return fallback;\n        }\n\n        const result = BuiltInConverters.processArrayConverter(parsed, resolvedConverter, this.envService.isStrict());\n        return result as TFallback;\n    }\n\n    private processCustomConverter<TFallback>(\n        key: EnvKeyInput,\n        fallback: TFallback | undefined,\n        resolvedConverter: EnvaptConverter<TFallback>,\n        _hasFallback: boolean // hasFallback is not needed because customConverter is called even if the raw value is undefined\n    ): TFallback | null | undefined {\n        Validator.customConvertor(resolvedConverter);\n\n        const raw = this.envService.get(key, undefined);\n\n        return resolvedConverter(raw, fallback);\n    }\n\n    private resolveConverter<TFallback>(\n        converter: EnvaptConverter<TFallback> | undefined,\n        fallback: TFallback | undefined\n    ): EnvaptConverter<TFallback> {\n        if (converter) return converter;\n\n        const fallbackType = typeof fallback;\n        if (fallbackType === 'number') return 'number';\n        if (fallbackType === 'boolean') return 'boolean';\n        if (fallbackType === 'bigint') return 'bigint';\n        if (fallbackType === 'symbol') return 'symbol';\n        return 'string';\n    }\n\n    // Single dispatch site for decorator + `Envapter.parse()` so error codes (208 / 209 / 305)\n    // stay consistent. Missing+no-fallback throws here so callers don't duplicate the check.\n    convertWithSchema(key: EnvKeyInput, schema: StandardSchemaV1, fallback: unknown, hasFallback: boolean): unknown {\n        const raw = this.envService.get(key, undefined);\n\n        if (raw === undefined) {\n            if (hasFallback) return fallback;\n            throw new EnvaptError(\n                EnvaptErrorCodes.MissingEnvValue,\n                `Required environment variable \"${formatKeyForError(key)}\" is missing or empty.`\n            );\n        }\n\n        let outcome: StandardSchemaV1.Result<unknown> | Promise<StandardSchemaV1.Result<unknown>>;\n        try {\n            outcome = schema['~standard'].validate(raw);\n        } catch (cause) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.SchemaThrew,\n                `Schema for \"${formatKeyForError(key)}\" threw during validation: ${(cause as Error).message}`,\n                { cause }\n            );\n        }\n\n        if (outcome instanceof Promise) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidUserDefinedConfig,\n                `Schema for \"${formatKeyForError(key)}\" returned a Promise. envapt requires synchronous schemas; use a sync validator or perform async checks outside the env layer.`\n            );\n        }\n\n        if (outcome.issues !== undefined) {\n            const first = outcome.issues[0];\n            const firstMessage = first?.message ?? 'no issue message';\n            throw new EnvaptError(\n                EnvaptErrorCodes.SchemaValidationFailed,\n                `Schema validation failed for \"${formatKeyForError(key)}\": ${firstMessage}`,\n                { issues: outcome.issues }\n            );\n        }\n\n        return outcome.value;\n    }\n}\n"],"mappings":"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"}

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

@@ -0,0 +1 @@
+{"version":3,"file":"AdvancedMethods.cjs","names":["PrimitiveMethods","EnvaptError"],"sources":["../../../src/core/AdvancedMethods.ts"],"sourcesContent":["import { EnvaptError, EnvaptErrorCodes } from '../Error';\nimport { PrimitiveMethods } from './PrimitiveMethods';\n\nimport type { ArrayOf } from '../converters';\nimport type { InferSchemaOutput, StandardSchemaV1 } from '../StandardSchema';\nimport type {\n    AdvancedConverterReturn,\n    BuiltInConverter,\n    ConditionalReturn,\n    ConverterFunction,\n    EnvKeyInput,\n    InferConverterReturnType,\n    SchemaConstraint,\n    TimeFallback\n} from '../types';\n\ninterface GetUsingRequiredOptions<TConverter> {\n    converter: TConverter;\n    required: true;\n}\n\ninterface GetWithRequiredOptions<TReturnType> {\n    converter: ConverterFunction<TReturnType>;\n    required: true;\n}\n\nfunction isOptionsBag(value: unknown): value is { converter: unknown; required?: boolean; fallback?: unknown } {\n    // `ArrayOf` tokens have `of`/`delimiter` but no `converter` key, so the presence of\n    // `converter` discriminates the options-bag form from a positional converter token.\n    return typeof value === 'object' && value !== null && 'converter' in value;\n}\n\nfunction formatKeyForError(key: EnvKeyInput): string {\n    return Array.isArray(key) ? `[${key.join(', ')}]` : String(key);\n}\n\n/**\n * Mixin for advanced methods for environment variable conversion using built-in and custom converters\n * @internal\n */\nexport class AdvancedMethods extends PrimitiveMethods {\n    /**\n     * Get an environment variable using a built-in converter.\n     *\n     * Supports both scalar tokens (e.g. `Converters.Number`) and `ArrayOf<...>` tokens\n     * produced by `Converters.array(...)`. The key can be a single name or an ordered list;\n     * the first defined value wins.\n     */\n    // Time-specific overload must precede the generic BuiltInConverter overload so it wins\n    // overload resolution (TimeFallback accepts time-strings like `'10s'`).\n    static getUsing<TFallback extends TimeFallback | undefined = undefined>(\n        key: EnvKeyInput,\n        converter: 'time',\n        fallback?: TFallback\n    ): ConditionalReturn<number, TFallback>;\n    static getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(\n        key: EnvKeyInput,\n        converter: TConverter,\n        fallback?: TFallback\n    ): AdvancedConverterReturn<TConverter, TFallback>;\n    static getUsing<TReturn>(key: EnvKeyInput, converter: BuiltInConverter | ArrayOf, fallback?: TReturn): TReturn;\n    static getUsing(key: EnvKeyInput, options: GetUsingRequiredOptions<'time'>): number;\n    static getUsing<TConverter extends BuiltInConverter | ArrayOf>(\n        key: EnvKeyInput,\n        options: GetUsingRequiredOptions<TConverter>\n    ): InferConverterReturnType<TConverter>;\n    static getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(\n        key: EnvKeyInput,\n        converterOrOptions: TConverter | GetUsingRequiredOptions<TConverter>,\n        fallback?: TFallback\n    ): AdvancedConverterReturn<TConverter, TFallback> {\n        if (isOptionsBag(converterOrOptions)) {\n            const options = converterOrOptions;\n            const { key: resolvedKey, value } = this.resolveKeyInput(key);\n\n            if (value === undefined || value.trim() === '') {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.MissingEnvValue,\n                    `Required environment variable \"${formatKeyForError(key)}\" is missing or empty.`\n                );\n            }\n\n            const result = this.valueConverter.convertValue(\n                resolvedKey,\n                undefined,\n                options.converter as TConverter,\n                false\n            );\n            return result as AdvancedConverterReturn<TConverter, TFallback>;\n        }\n\n        const converter = converterOrOptions as TConverter;\n        const { key: resolvedKey, value } = this.resolveKeyInput(key);\n\n        // No env value AND no fallback: return undefined to match primitive-method semantics.\n        // Otherwise route through the parser so asymmetric fallback types (TimeFallback,\n        // TimeFallback[] for `of: time` arrays) get coerced to the declared return type.\n        if (this.treatAsMissing(value) && fallback === undefined) {\n            return undefined as AdvancedConverterReturn<TConverter, TFallback>;\n        }\n\n        const hasFallback = fallback !== undefined;\n        const result = this.valueConverter.convertValue(resolvedKey, fallback, converter, hasFallback);\n\n        return result as AdvancedConverterReturn<TConverter, TFallback>;\n    }\n\n    /**\n     * @see {@link AdvancedMethods.getUsing}\n     */\n    getUsing<TFallback extends TimeFallback | undefined = undefined>(\n        key: EnvKeyInput,\n        converter: 'time',\n        fallback?: TFallback\n    ): ConditionalReturn<number, TFallback>;\n    getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(\n        key: EnvKeyInput,\n        converter: TConverter,\n        fallback?: TFallback\n    ): AdvancedConverterReturn<TConverter, TFallback>;\n    getUsing<TReturn>(key: EnvKeyInput, converter: BuiltInConverter | ArrayOf, fallback?: TReturn): TReturn;\n    getUsing(key: EnvKeyInput, options: GetUsingRequiredOptions<'time'>): number;\n    getUsing<TConverter extends BuiltInConverter | ArrayOf>(\n        key: EnvKeyInput,\n        options: GetUsingRequiredOptions<TConverter>\n    ): InferConverterReturnType<TConverter>;\n    getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(\n        key: EnvKeyInput,\n        converterOrOptions: TConverter | GetUsingRequiredOptions<TConverter>,\n        fallback?: TFallback\n    ): AdvancedConverterReturn<TConverter, TFallback> {\n        return AdvancedMethods.getUsing(key, converterOrOptions as TConverter, fallback);\n    }\n\n    /**\n     * Get an environment variable using a custom converter function.\n     * Accepts a single key or an ordered list for automatic fallback.\n     */\n    static getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(\n        key: EnvKeyInput,\n        converter: ConverterFunction<TReturnType>,\n        fallback?: TFallback\n    ): ConditionalReturn<TReturnType, TFallback>;\n    static getWith<TReturnType>(key: EnvKeyInput, options: GetWithRequiredOptions<TReturnType>): TReturnType;\n    static getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(\n        key: EnvKeyInput,\n        converterOrOptions: ConverterFunction<TReturnType> | GetWithRequiredOptions<TReturnType>,\n        fallback?: TFallback\n    ): ConditionalReturn<TReturnType, TFallback> {\n        if (isOptionsBag(converterOrOptions)) {\n            const options = converterOrOptions;\n            const { key: resolvedKey, value } = this.resolveKeyInput(key);\n\n            if (value === undefined || value.trim() === '') {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.MissingEnvValue,\n                    `Required environment variable \"${formatKeyForError(key)}\" is missing or empty.`\n                );\n            }\n\n            const result = this.valueConverter.convertValue(\n                resolvedKey,\n                undefined,\n                options.converter as ConverterFunction<undefined>,\n                false\n            );\n            return result as ConditionalReturn<TReturnType, TFallback>;\n        }\n\n        // Check if variable exists first, for consistency with primitive methods\n        const { key: resolvedKey, value } = this.resolveKeyInput(key);\n        if (this.treatAsMissing(value)) return fallback as ConditionalReturn<TReturnType, TFallback>;\n\n        const hasFallback = fallback !== undefined;\n        // Convert the converter to match the expected signature via unknown\n        const result = this.valueConverter.convertValue(\n            resolvedKey,\n            fallback,\n            converterOrOptions as unknown as ConverterFunction<TFallback>,\n            hasFallback\n        );\n\n        return result as ConditionalReturn<TReturnType, TFallback>;\n    }\n\n    /**\n     * @see {@link AdvancedMethods.getWith}\n     */\n    getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(\n        key: EnvKeyInput,\n        converter: ConverterFunction<TReturnType>,\n        fallback?: TFallback\n    ): ConditionalReturn<TReturnType, TFallback>;\n    getWith<TReturnType>(key: EnvKeyInput, options: GetWithRequiredOptions<TReturnType>): TReturnType;\n    getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(\n        key: EnvKeyInput,\n        converterOrOptions: ConverterFunction<TReturnType> | GetWithRequiredOptions<TReturnType>,\n        fallback?: TFallback\n    ): ConditionalReturn<TReturnType, TFallback> {\n        return AdvancedMethods.getWith(key, converterOrOptions as ConverterFunction<TReturnType>, fallback);\n    }\n\n    /**\n     * Validate an environment variable through a {@link StandardSchemaV1}-conformant schema\n     * (zod, valibot, arktype, etc). Throws `MissingEnvValue` if the env value is absent and\n     * no fallback is provided. The fallback, when provided, is returned as-is on missing;\n     * it does NOT pass through the schema (mirrors custom-converter behavior).\n     *\n     * Synchronous schemas only. A Promise-returning `validate` triggers an\n     * `InvalidUserDefinedConfig` throw at the call site.\n     *\n     * @example\n     * ```ts\n     * import { z } from 'zod';\n     * const port = Envapter.parse('PORT', z.coerce.number().min(1024).max(65535), 3000);\n     * ```\n     */\n    static parse<Schema extends StandardSchemaV1>(\n        key: EnvKeyInput,\n        schema: SchemaConstraint<Schema>,\n        fallback?: InferSchemaOutput<Schema>\n    ): InferSchemaOutput<Schema> {\n        const hasFallback = arguments.length > 2;\n        // SchemaConstraint resolves to the unsatisfiable SchemaMustBeSync brand for async\n        // schemas, so reaching this body means the input is structurally a sync Schema.\n        const result = this.valueConverter.convertWithSchema(\n            key,\n            schema as unknown as StandardSchemaV1,\n            fallback,\n            hasFallback\n        );\n        return result;\n    }\n\n    /**\n     * @see {@link AdvancedMethods.parse}\n     */\n    parse<Schema extends StandardSchemaV1>(\n        key: EnvKeyInput,\n        schema: SchemaConstraint<Schema>,\n        fallback?: InferSchemaOutput<Schema>\n    ): InferSchemaOutput<Schema> {\n        const hasFallback = arguments.length > 2;\n        const result = AdvancedMethods.valueConverter.convertWithSchema(\n            key,\n            schema as unknown as StandardSchemaV1,\n            fallback,\n            hasFallback\n        );\n        return result;\n    }\n}\n"],"mappings":"oEA0BA,SAAS,EAAa,EAAyF,CAG3G,OAAO,OAAO,GAAU,YAAY,GAAkB,cAAe,CACzE,CAEA,SAAS,EAAkB,EAA0B,CACjD,OAAO,MAAM,QAAQ,CAAG,EAAI,IAAI,EAAI,KAAK,IAAI,EAAE,GAAK,OAAO,CAAG,CAClE,CAMA,IAAa,EAAb,MAAa,UAAwBA,EAAAA,gBAAiB,CA0BlD,OAAO,SACH,EACA,EACA,EAC8C,CAC9C,GAAI,EAAa,CAAkB,EAAG,CAClC,IAAM,EAAU,EACV,CAAE,IAAK,EAAa,SAAU,KAAK,gBAAgB,CAAG,EAE5D,GAAI,IAAU,IAAA,IAAa,EAAM,KAAK,IAAM,GACxC,MAAM,IAAIC,EAAAA,YAAAA,IAEN,kCAAkC,EAAkB,CAAG,EAAE,uBAC7D,EASJ,OANe,KAAK,eAAe,aAC/B,EACA,IAAA,GACA,EAAQ,UACR,EAEQ,CAChB,CAEA,IAAM,EAAY,EACZ,CAAE,IAAK,EAAa,SAAU,KAAK,gBAAgB,CAAG,EAK5D,GAAI,KAAK,eAAe,CAAK,GAAK,IAAa,IAAA,GAC3C,OAGJ,IAAM,EAAc,IAAa,IAAA,GAGjC,OAFe,KAAK,eAAe,aAAa,EAAa,EAAU,EAAW,CAEtE,CAChB,CAqBA,SACI,EACA,EACA,EAC8C,CAC9C,OAAO,EAAgB,SAAS,EAAK,EAAkC,CAAQ,CACnF,CAYA,OAAO,QACH,EACA,EACA,EACyC,CACzC,GAAI,EAAa,CAAkB,EAAG,CAClC,IAAM,EAAU,EACV,CAAE,IAAK,EAAa,SAAU,KAAK,gBAAgB,CAAG,EAE5D,GAAI,IAAU,IAAA,IAAa,EAAM,KAAK,IAAM,GACxC,MAAM,IAAIA,EAAAA,YAAAA,IAEN,kCAAkC,EAAkB,CAAG,EAAE,uBAC7D,EASJ,OANe,KAAK,eAAe,aAC/B,EACA,IAAA,GACA,EAAQ,UACR,EAEQ,CAChB,CAGA,GAAM,CAAE,IAAK,EAAa,SAAU,KAAK,gBAAgB,CAAG,EAC5D,GAAI,KAAK,eAAe,CAAK,EAAG,OAAO,EAEvC,IAAM,EAAc,IAAa,IAAA,GASjC,OAPe,KAAK,eAAe,aAC/B,EACA,EACA,EACA,CAGQ,CAChB,CAWA,QACI,EACA,EACA,EACyC,CACzC,OAAO,EAAgB,QAAQ,EAAK,EAAsD,CAAQ,CACtG,CAiBA,OAAO,MACH,EACA,EACA,EACyB,CACzB,IAAM,EAAc,UAAU,OAAS,EASvC,OANe,KAAK,eAAe,kBAC/B,EACA,EACA,EACA,CAEQ,CAChB,CAKA,MACI,EACA,EACA,EACyB,CACzB,IAAM,EAAc,UAAU,OAAS,EAOvC,OANe,EAAgB,eAAe,kBAC1C,EACA,EACA,EACA,CAEQ,CAChB,CACJ"}

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

@@ -0,0 +1,76 @@
+import { ArrayOf } from "../converters/Converters.mjs";
+import { AdvancedConverterReturn, BuiltInConverter, ConditionalReturn, ConverterFunction, InferConverterReturnType, TimeFallback } from "../types/Conversion.mjs";
+import { InferSchemaOutput, StandardSchemaV1 } from "../StandardSchema.mjs";
+import { SchemaConstraint } from "../types/Schema.mjs";
+import { EnvKeyInput } from "../types/Env.mjs";
+import { PrimitiveMethods } from "./PrimitiveMethods.mjs";
+
+//#region src/core/AdvancedMethods.d.ts
+interface GetUsingRequiredOptions<TConverter> {
+  converter: TConverter;
+  required: true;
+}
+interface GetWithRequiredOptions<TReturnType> {
+  converter: ConverterFunction<TReturnType>;
+  required: true;
+}
+/**
+ * Mixin for advanced methods for environment variable conversion using built-in and custom converters
+ * @internal
+ */
+declare class AdvancedMethods extends PrimitiveMethods {
+  /**
+   * Get an environment variable using a built-in converter.
+   *
+   * Supports both scalar tokens (e.g. `Converters.Number`) and `ArrayOf<...>` tokens
+   * produced by `Converters.array(...)`. The key can be a single name or an ordered list;
+   * the first defined value wins.
+   */
+  static getUsing<TFallback extends TimeFallback | undefined = undefined>(key: EnvKeyInput, converter: 'time', fallback?: TFallback): ConditionalReturn<number, TFallback>;
+  static getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(key: EnvKeyInput, converter: TConverter, fallback?: TFallback): AdvancedConverterReturn<TConverter, TFallback>;
+  static getUsing<TReturn>(key: EnvKeyInput, converter: BuiltInConverter | ArrayOf, fallback?: TReturn): TReturn;
+  static getUsing(key: EnvKeyInput, options: GetUsingRequiredOptions<'time'>): number;
+  static getUsing<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, options: GetUsingRequiredOptions<TConverter>): InferConverterReturnType<TConverter>;
+  /**
+   * @see {@link AdvancedMethods.getUsing}
+   */
+  getUsing<TFallback extends TimeFallback | undefined = undefined>(key: EnvKeyInput, converter: 'time', fallback?: TFallback): ConditionalReturn<number, TFallback>;
+  getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(key: EnvKeyInput, converter: TConverter, fallback?: TFallback): AdvancedConverterReturn<TConverter, TFallback>;
+  getUsing<TReturn>(key: EnvKeyInput, converter: BuiltInConverter | ArrayOf, fallback?: TReturn): TReturn;
+  getUsing(key: EnvKeyInput, options: GetUsingRequiredOptions<'time'>): number;
+  getUsing<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, options: GetUsingRequiredOptions<TConverter>): InferConverterReturnType<TConverter>;
+  /**
+   * Get an environment variable using a custom converter function.
+   * Accepts a single key or an ordered list for automatic fallback.
+   */
+  static getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(key: EnvKeyInput, converter: ConverterFunction<TReturnType>, fallback?: TFallback): ConditionalReturn<TReturnType, TFallback>;
+  static getWith<TReturnType>(key: EnvKeyInput, options: GetWithRequiredOptions<TReturnType>): TReturnType;
+  /**
+   * @see {@link AdvancedMethods.getWith}
+   */
+  getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(key: EnvKeyInput, converter: ConverterFunction<TReturnType>, fallback?: TFallback): ConditionalReturn<TReturnType, TFallback>;
+  getWith<TReturnType>(key: EnvKeyInput, options: GetWithRequiredOptions<TReturnType>): TReturnType;
+  /**
+   * Validate an environment variable through a {@link StandardSchemaV1}-conformant schema
+   * (zod, valibot, arktype, etc). Throws `MissingEnvValue` if the env value is absent and
+   * no fallback is provided. The fallback, when provided, is returned as-is on missing;
+   * it does NOT pass through the schema (mirrors custom-converter behavior).
+   *
+   * Synchronous schemas only. A Promise-returning `validate` triggers an
+   * `InvalidUserDefinedConfig` throw at the call site.
+   *
+   * @example
+   * ```ts
+   * import { z } from 'zod';
+   * const port = Envapter.parse('PORT', z.coerce.number().min(1024).max(65535), 3000);
+   * ```
+   */
+  static parse<Schema extends StandardSchemaV1>(key: EnvKeyInput, schema: SchemaConstraint<Schema>, fallback?: InferSchemaOutput<Schema>): InferSchemaOutput<Schema>;
+  /**
+   * @see {@link AdvancedMethods.parse}
+   */
+  parse<Schema extends StandardSchemaV1>(key: EnvKeyInput, schema: SchemaConstraint<Schema>, fallback?: InferSchemaOutput<Schema>): InferSchemaOutput<Schema>;
+}
+//#endregion
+export { AdvancedMethods };
+//# sourceMappingURL=AdvancedMethods.d.mts.map

package/dist/node/core/AdvancedMethods.mjs

@@ -0,0 +1,2 @@
+import{EnvaptError as e}from"../Error.mjs";import{PrimitiveMethods as t}from"./PrimitiveMethods.mjs";function n(e){return typeof e==`object`&&!!e&&`converter`in e}function r(e){return Array.isArray(e)?`[${e.join(`, `)}]`:String(e)}var i=class i extends t{static getUsing(t,i,a){if(n(i)){let n=i,{key:a,value:o}=this.resolveKeyInput(t);if(o===void 0||o.trim()===``)throw new e(305,`Required environment variable "${r(t)}" is missing or empty.`);return this.valueConverter.convertValue(a,void 0,n.converter,!1)}let o=i,{key:s,value:c}=this.resolveKeyInput(t);if(this.treatAsMissing(c)&&a===void 0)return;let l=a!==void 0;return this.valueConverter.convertValue(s,a,o,l)}getUsing(e,t,n){return i.getUsing(e,t,n)}static getWith(t,i,a){if(n(i)){let n=i,{key:a,value:o}=this.resolveKeyInput(t);if(o===void 0||o.trim()===``)throw new e(305,`Required environment variable "${r(t)}" is missing or empty.`);return this.valueConverter.convertValue(a,void 0,n.converter,!1)}let{key:o,value:s}=this.resolveKeyInput(t);if(this.treatAsMissing(s))return a;let c=a!==void 0;return this.valueConverter.convertValue(o,a,i,c)}getWith(e,t,n){return i.getWith(e,t,n)}static parse(e,t,n){let r=arguments.length>2;return this.valueConverter.convertWithSchema(e,t,n,r)}parse(e,t,n){let r=arguments.length>2;return i.valueConverter.convertWithSchema(e,t,n,r)}};export{i as AdvancedMethods};
+//# sourceMappingURL=AdvancedMethods.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AdvancedMethods.mjs","names":[],"sources":["../../../src/core/AdvancedMethods.ts"],"sourcesContent":["import { EnvaptError, EnvaptErrorCodes } from '../Error';\nimport { PrimitiveMethods } from './PrimitiveMethods';\n\nimport type { ArrayOf } from '../converters';\nimport type { InferSchemaOutput, StandardSchemaV1 } from '../StandardSchema';\nimport type {\n    AdvancedConverterReturn,\n    BuiltInConverter,\n    ConditionalReturn,\n    ConverterFunction,\n    EnvKeyInput,\n    InferConverterReturnType,\n    SchemaConstraint,\n    TimeFallback\n} from '../types';\n\ninterface GetUsingRequiredOptions<TConverter> {\n    converter: TConverter;\n    required: true;\n}\n\ninterface GetWithRequiredOptions<TReturnType> {\n    converter: ConverterFunction<TReturnType>;\n    required: true;\n}\n\nfunction isOptionsBag(value: unknown): value is { converter: unknown; required?: boolean; fallback?: unknown } {\n    // `ArrayOf` tokens have `of`/`delimiter` but no `converter` key, so the presence of\n    // `converter` discriminates the options-bag form from a positional converter token.\n    return typeof value === 'object' && value !== null && 'converter' in value;\n}\n\nfunction formatKeyForError(key: EnvKeyInput): string {\n    return Array.isArray(key) ? `[${key.join(', ')}]` : String(key);\n}\n\n/**\n * Mixin for advanced methods for environment variable conversion using built-in and custom converters\n * @internal\n */\nexport class AdvancedMethods extends PrimitiveMethods {\n    /**\n     * Get an environment variable using a built-in converter.\n     *\n     * Supports both scalar tokens (e.g. `Converters.Number`) and `ArrayOf<...>` tokens\n     * produced by `Converters.array(...)`. The key can be a single name or an ordered list;\n     * the first defined value wins.\n     */\n    // Time-specific overload must precede the generic BuiltInConverter overload so it wins\n    // overload resolution (TimeFallback accepts time-strings like `'10s'`).\n    static getUsing<TFallback extends TimeFallback | undefined = undefined>(\n        key: EnvKeyInput,\n        converter: 'time',\n        fallback?: TFallback\n    ): ConditionalReturn<number, TFallback>;\n    static getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(\n        key: EnvKeyInput,\n        converter: TConverter,\n        fallback?: TFallback\n    ): AdvancedConverterReturn<TConverter, TFallback>;\n    static getUsing<TReturn>(key: EnvKeyInput, converter: BuiltInConverter | ArrayOf, fallback?: TReturn): TReturn;\n    static getUsing(key: EnvKeyInput, options: GetUsingRequiredOptions<'time'>): number;\n    static getUsing<TConverter extends BuiltInConverter | ArrayOf>(\n        key: EnvKeyInput,\n        options: GetUsingRequiredOptions<TConverter>\n    ): InferConverterReturnType<TConverter>;\n    static getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(\n        key: EnvKeyInput,\n        converterOrOptions: TConverter | GetUsingRequiredOptions<TConverter>,\n        fallback?: TFallback\n    ): AdvancedConverterReturn<TConverter, TFallback> {\n        if (isOptionsBag(converterOrOptions)) {\n            const options = converterOrOptions;\n            const { key: resolvedKey, value } = this.resolveKeyInput(key);\n\n            if (value === undefined || value.trim() === '') {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.MissingEnvValue,\n                    `Required environment variable \"${formatKeyForError(key)}\" is missing or empty.`\n                );\n            }\n\n            const result = this.valueConverter.convertValue(\n                resolvedKey,\n                undefined,\n                options.converter as TConverter,\n                false\n            );\n            return result as AdvancedConverterReturn<TConverter, TFallback>;\n        }\n\n        const converter = converterOrOptions as TConverter;\n        const { key: resolvedKey, value } = this.resolveKeyInput(key);\n\n        // No env value AND no fallback: return undefined to match primitive-method semantics.\n        // Otherwise route through the parser so asymmetric fallback types (TimeFallback,\n        // TimeFallback[] for `of: time` arrays) get coerced to the declared return type.\n        if (this.treatAsMissing(value) && fallback === undefined) {\n            return undefined as AdvancedConverterReturn<TConverter, TFallback>;\n        }\n\n        const hasFallback = fallback !== undefined;\n        const result = this.valueConverter.convertValue(resolvedKey, fallback, converter, hasFallback);\n\n        return result as AdvancedConverterReturn<TConverter, TFallback>;\n    }\n\n    /**\n     * @see {@link AdvancedMethods.getUsing}\n     */\n    getUsing<TFallback extends TimeFallback | undefined = undefined>(\n        key: EnvKeyInput,\n        converter: 'time',\n        fallback?: TFallback\n    ): ConditionalReturn<number, TFallback>;\n    getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(\n        key: EnvKeyInput,\n        converter: TConverter,\n        fallback?: TFallback\n    ): AdvancedConverterReturn<TConverter, TFallback>;\n    getUsing<TReturn>(key: EnvKeyInput, converter: BuiltInConverter | ArrayOf, fallback?: TReturn): TReturn;\n    getUsing(key: EnvKeyInput, options: GetUsingRequiredOptions<'time'>): number;\n    getUsing<TConverter extends BuiltInConverter | ArrayOf>(\n        key: EnvKeyInput,\n        options: GetUsingRequiredOptions<TConverter>\n    ): InferConverterReturnType<TConverter>;\n    getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(\n        key: EnvKeyInput,\n        converterOrOptions: TConverter | GetUsingRequiredOptions<TConverter>,\n        fallback?: TFallback\n    ): AdvancedConverterReturn<TConverter, TFallback> {\n        return AdvancedMethods.getUsing(key, converterOrOptions as TConverter, fallback);\n    }\n\n    /**\n     * Get an environment variable using a custom converter function.\n     * Accepts a single key or an ordered list for automatic fallback.\n     */\n    static getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(\n        key: EnvKeyInput,\n        converter: ConverterFunction<TReturnType>,\n        fallback?: TFallback\n    ): ConditionalReturn<TReturnType, TFallback>;\n    static getWith<TReturnType>(key: EnvKeyInput, options: GetWithRequiredOptions<TReturnType>): TReturnType;\n    static getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(\n        key: EnvKeyInput,\n        converterOrOptions: ConverterFunction<TReturnType> | GetWithRequiredOptions<TReturnType>,\n        fallback?: TFallback\n    ): ConditionalReturn<TReturnType, TFallback> {\n        if (isOptionsBag(converterOrOptions)) {\n            const options = converterOrOptions;\n            const { key: resolvedKey, value } = this.resolveKeyInput(key);\n\n            if (value === undefined || value.trim() === '') {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.MissingEnvValue,\n                    `Required environment variable \"${formatKeyForError(key)}\" is missing or empty.`\n                );\n            }\n\n            const result = this.valueConverter.convertValue(\n                resolvedKey,\n                undefined,\n                options.converter as ConverterFunction<undefined>,\n                false\n            );\n            return result as ConditionalReturn<TReturnType, TFallback>;\n        }\n\n        // Check if variable exists first, for consistency with primitive methods\n        const { key: resolvedKey, value } = this.resolveKeyInput(key);\n        if (this.treatAsMissing(value)) return fallback as ConditionalReturn<TReturnType, TFallback>;\n\n        const hasFallback = fallback !== undefined;\n        // Convert the converter to match the expected signature via unknown\n        const result = this.valueConverter.convertValue(\n            resolvedKey,\n            fallback,\n            converterOrOptions as unknown as ConverterFunction<TFallback>,\n            hasFallback\n        );\n\n        return result as ConditionalReturn<TReturnType, TFallback>;\n    }\n\n    /**\n     * @see {@link AdvancedMethods.getWith}\n     */\n    getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(\n        key: EnvKeyInput,\n        converter: ConverterFunction<TReturnType>,\n        fallback?: TFallback\n    ): ConditionalReturn<TReturnType, TFallback>;\n    getWith<TReturnType>(key: EnvKeyInput, options: GetWithRequiredOptions<TReturnType>): TReturnType;\n    getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(\n        key: EnvKeyInput,\n        converterOrOptions: ConverterFunction<TReturnType> | GetWithRequiredOptions<TReturnType>,\n        fallback?: TFallback\n    ): ConditionalReturn<TReturnType, TFallback> {\n        return AdvancedMethods.getWith(key, converterOrOptions as ConverterFunction<TReturnType>, fallback);\n    }\n\n    /**\n     * Validate an environment variable through a {@link StandardSchemaV1}-conformant schema\n     * (zod, valibot, arktype, etc). Throws `MissingEnvValue` if the env value is absent and\n     * no fallback is provided. The fallback, when provided, is returned as-is on missing;\n     * it does NOT pass through the schema (mirrors custom-converter behavior).\n     *\n     * Synchronous schemas only. A Promise-returning `validate` triggers an\n     * `InvalidUserDefinedConfig` throw at the call site.\n     *\n     * @example\n     * ```ts\n     * import { z } from 'zod';\n     * const port = Envapter.parse('PORT', z.coerce.number().min(1024).max(65535), 3000);\n     * ```\n     */\n    static parse<Schema extends StandardSchemaV1>(\n        key: EnvKeyInput,\n        schema: SchemaConstraint<Schema>,\n        fallback?: InferSchemaOutput<Schema>\n    ): InferSchemaOutput<Schema> {\n        const hasFallback = arguments.length > 2;\n        // SchemaConstraint resolves to the unsatisfiable SchemaMustBeSync brand for async\n        // schemas, so reaching this body means the input is structurally a sync Schema.\n        const result = this.valueConverter.convertWithSchema(\n            key,\n            schema as unknown as StandardSchemaV1,\n            fallback,\n            hasFallback\n        );\n        return result;\n    }\n\n    /**\n     * @see {@link AdvancedMethods.parse}\n     */\n    parse<Schema extends StandardSchemaV1>(\n        key: EnvKeyInput,\n        schema: SchemaConstraint<Schema>,\n        fallback?: InferSchemaOutput<Schema>\n    ): InferSchemaOutput<Schema> {\n        const hasFallback = arguments.length > 2;\n        const result = AdvancedMethods.valueConverter.convertWithSchema(\n            key,\n            schema as unknown as StandardSchemaV1,\n            fallback,\n            hasFallback\n        );\n        return result;\n    }\n}\n"],"mappings":"qGA0BA,SAAS,EAAa,EAAyF,CAG3G,OAAO,OAAO,GAAU,YAAY,GAAkB,cAAe,CACzE,CAEA,SAAS,EAAkB,EAA0B,CACjD,OAAO,MAAM,QAAQ,CAAG,EAAI,IAAI,EAAI,KAAK,IAAI,EAAE,GAAK,OAAO,CAAG,CAClE,CAMA,IAAa,EAAb,MAAa,UAAwB,CAAiB,CA0BlD,OAAO,SACH,EACA,EACA,EAC8C,CAC9C,GAAI,EAAa,CAAkB,EAAG,CAClC,IAAM,EAAU,EACV,CAAE,IAAK,EAAa,SAAU,KAAK,gBAAgB,CAAG,EAE5D,GAAI,IAAU,IAAA,IAAa,EAAM,KAAK,IAAM,GACxC,MAAM,IAAI,EAAA,IAEN,kCAAkC,EAAkB,CAAG,EAAE,uBAC7D,EASJ,OANe,KAAK,eAAe,aAC/B,EACA,IAAA,GACA,EAAQ,UACR,EAEQ,CAChB,CAEA,IAAM,EAAY,EACZ,CAAE,IAAK,EAAa,SAAU,KAAK,gBAAgB,CAAG,EAK5D,GAAI,KAAK,eAAe,CAAK,GAAK,IAAa,IAAA,GAC3C,OAGJ,IAAM,EAAc,IAAa,IAAA,GAGjC,OAFe,KAAK,eAAe,aAAa,EAAa,EAAU,EAAW,CAEtE,CAChB,CAqBA,SACI,EACA,EACA,EAC8C,CAC9C,OAAO,EAAgB,SAAS,EAAK,EAAkC,CAAQ,CACnF,CAYA,OAAO,QACH,EACA,EACA,EACyC,CACzC,GAAI,EAAa,CAAkB,EAAG,CAClC,IAAM,EAAU,EACV,CAAE,IAAK,EAAa,SAAU,KAAK,gBAAgB,CAAG,EAE5D,GAAI,IAAU,IAAA,IAAa,EAAM,KAAK,IAAM,GACxC,MAAM,IAAI,EAAA,IAEN,kCAAkC,EAAkB,CAAG,EAAE,uBAC7D,EASJ,OANe,KAAK,eAAe,aAC/B,EACA,IAAA,GACA,EAAQ,UACR,EAEQ,CAChB,CAGA,GAAM,CAAE,IAAK,EAAa,SAAU,KAAK,gBAAgB,CAAG,EAC5D,GAAI,KAAK,eAAe,CAAK,EAAG,OAAO,EAEvC,IAAM,EAAc,IAAa,IAAA,GASjC,OAPe,KAAK,eAAe,aAC/B,EACA,EACA,EACA,CAGQ,CAChB,CAWA,QACI,EACA,EACA,EACyC,CACzC,OAAO,EAAgB,QAAQ,EAAK,EAAsD,CAAQ,CACtG,CAiBA,OAAO,MACH,EACA,EACA,EACyB,CACzB,IAAM,EAAc,UAAU,OAAS,EASvC,OANe,KAAK,eAAe,kBAC/B,EACA,EACA,EACA,CAEQ,CAChB,CAKA,MACI,EACA,EACA,EACyB,CACzB,IAAM,EAAc,UAAU,OAAS,EAOvC,OANe,EAAgB,eAAe,kBAC1C,EACA,EACA,EACA,CAEQ,CAChB,CACJ"}

package/dist/node/core/EnvapterBase.cjs

@@ -0,0 +1,2 @@
+const e=require("../Error.cjs"),t=require("../Validators.cjs"),n=require("../runtime.cjs"),r=require("../Debug.cjs"),i=require("../Dotenv.cjs"),a=require("../sources/UnboundEnvSource.cjs"),o=new Map;var s=class s{static _envPaths=[`.env`];static _envPathsExplicitlySet=!1;static _baseDir=void 0;static _userDefinedEnvFileOptions={};static _strict=!1;static _syncProcessEnv=!1;static _dotenvAddedKeys=new Set;static _source=new a.UnboundEnvSource;static set strict(e){s._strict=e,this.refreshCache()}static get strict(){return s._strict}static set debug(e){r.setDebugLevel(e)}static get debug(){return r.getDebugLevel()}static set syncProcessEnv(e){t.Validator.validateSyncProcessEnv(e);let n=s._syncProcessEnv;s._syncProcessEnv=e,!n&&e&&o.size>0&&this.mirrorToProcessEnv()}static get syncProcessEnv(){return s._syncProcessEnv}static treatAsMissing(e){return!!(e===void 0||e===``||s._strict&&e.trim()===``)}static resolveAgainstBase(e){let t=s._baseDir;if(t===void 0)return e;let n=s._source;return n.supportsFiles?n.resolvePath(t,e):e}static assertFileApiSupported(t,n){if(!n.supportsFiles)throw new e.EnvaptError(306,`${t} requires a filesystem-backed source; the bound source does not support .env files.`)}static sourceFileExists(e){let t=s._source;return t.supportsFiles?t.readFile(e,`utf8`)!==void 0:!1}static refreshCache(){o.clear(),s._dotenvAddedKeys=new Set,r.debugVerbose(`cache cleared, reloading config`),this.config}static mirrorToProcessEnv(){if(s._dotenvAddedKeys.size===0)return;let e=s._source;if(!e.supportsFiles)return;let t={};for(let e of s._dotenvAddedKeys){let n=o.get(e);typeof n==`string`&&(t[e]=n,r.debugVerbose(`mirrored ${e} to the ambient environment`))}e.writeVars(t),r.debugVerbose(`mirrored ${s._dotenvAddedKeys.size} keys to the ambient environment`)}static resolveEffectivePaths(){return this._envPaths.map(e=>this.resolveAgainstBase(e))}static resolveKeyInput(t){let n=Array.isArray(t)?t:[t];if(n.length===0)throw new e.EnvaptError(304,`At least one environment key must be provided.`);if(n.some(e=>typeof e!=`string`))throw new e.EnvaptError(304,`Environment keys must be strings.`);if(n.some(e=>e.trim()===``))throw new e.EnvaptError(304,`Environment keys cannot be empty strings.`);for(let e of n){let t=this.config.get(e);if(t!==void 0)return{key:e,value:t}}return{key:n[0],value:void 0}}static get config(){if(o.size===0){let e=s._source,t={...e.readVars()},n=new Set;if(e.supportsFiles){let a=this.resolveEffectivePaths();r.debugVerbose(`effective .env paths: ${a.length===0?`(none)`:a.join(`, `)}`);try{n=i.loadDotenv({...this._userDefinedEnvFileOptions,path:a,processEnv:t,readFile:e.readFile.bind(e)})}catch{}}s._dotenvAddedKeys=n;for(let[e,n]of Object.entries(t))o.set(e,n);r.debugVerbose(`cache populated: ${o.size} keys total`),s._syncProcessEnv&&this.mirrorToProcessEnv()}return o}static load(){this.config}static useSource(e){s._source=e,n.bindRuntimeFromSource(e),this.refreshCache()}getRaw(e){return s.resolveKeyInput(e).value}};exports.EnvaptCache=o,exports.EnvapterBase=s;
+//# sourceMappingURL=EnvapterBase.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EnvapterBase.cjs","names":["UnboundEnvSource","getDebugLevel","EnvaptError","loadDotenv"],"sources":["../../../src/core/EnvapterBase.ts"],"sourcesContent":["import { debugVerbose, getDebugLevel, setDebugLevel } from '../Debug';\nimport { loadDotenv } from '../Dotenv';\nimport { EnvaptError, EnvaptErrorCodes } from '../Error';\nimport { bindRuntimeFromSource } from '../runtime';\nimport { UnboundEnvSource } from '../sources/UnboundEnvSource';\nimport { Validator } from '../Validators';\n\nimport type { DebugLevel } from '../Debug';\nimport type { EnvFileOptions } from '../Dotenv';\nimport type { EnvKeyInput, EnvSource, FileEnvSource } from '../types';\n\n/** @internal */\nexport const EnvaptCache = new Map<string, unknown>();\n\n/** @internal */\nexport abstract class EnvapterBase {\n    protected static _envPaths: string[] = ['.env'];\n    protected static _envPathsExplicitlySet = false;\n    protected static _baseDir: string | undefined = undefined;\n    protected static _userDefinedEnvFileOptions: EnvFileOptions = {};\n    protected static _strict = false;\n    protected static _syncProcessEnv = false;\n    // Loader-written keys only (collisions skipped). Refilled on every cache rebuild.\n    protected static _dotenvAddedKeys: Set<string> = new Set<string>();\n    // Unbound by default so non-Node builds throw NoSourceBound on read until useSource() is called.\n    // NodeEnvapter's static block binds NodeEnvSource when referenced, so `import 'envapt'` needs no setup.\n    protected static _source: EnvSource = new UnboundEnvSource();\n\n    /**\n     * Enable or disable strict mode. Default `false`. Setting refreshes the cache so\n     * previously-cached converted values get re-evaluated under the new rule.\n     */\n    static set strict(value: boolean) {\n        // Anchored to EnvapterBase: `this._strict` would write an own-property on the subclass that base readers miss.\n        EnvapterBase._strict = value;\n        // `this`, not EnvapterBase: rebuild via the subclass so its `resolveEffectivePaths` override is honored.\n        this.refreshCache();\n    }\n\n    static get strict(): boolean {\n        return EnvapterBase._strict;\n    }\n\n    /**\n     * Set the debug log level. Defaults to `silent`. When unset, reads `ENVAPT_DEBUG` from the\n     * bound source on first access; the setter overrides any env-var value. Output goes to stderr\n     * on Node (the console elsewhere), prefixed with `[envapt]`.\n     */\n    static set debug(level: DebugLevel) {\n        setDebugLevel(level);\n    }\n\n    static get debug(): DebugLevel {\n        return getDebugLevel();\n    }\n\n    /**\n     * Opt-in mirror of dotenv-loaded keys back to `process.env`. Default `false`.\n     *\n     * Only keys the loader actually wrote are mirrored, so collision behavior follows\n     * `envFileOptions.override`: with the default `false`, pre-existing `process.env` values\n     * are preserved; with `true`, the file value wins in both the cache and the mirror.\n     *\n     * Flipping `false → true` mirrors the existing tracked delta immediately (no cache\n     * refresh). Flipping `true → false` is one-way: previously mirrored keys remain in\n     * `process.env` until the process exits.\n     */\n    static set syncProcessEnv(value: boolean) {\n        Validator.validateSyncProcessEnv(value);\n        const previous = EnvapterBase._syncProcessEnv;\n        // Anchored to EnvapterBase: `this._syncProcessEnv` would write an own-property on the subclass that base readers miss.\n        EnvapterBase._syncProcessEnv = value;\n        if (!previous && value && EnvaptCache.size > 0) this.mirrorToProcessEnv();\n    }\n\n    static get syncProcessEnv(): boolean {\n        return EnvapterBase._syncProcessEnv;\n    }\n\n    protected static treatAsMissing(value: string | undefined): boolean {\n        if (value === undefined || value === '') return true;\n        if (EnvapterBase._strict && value.trim() === '') return true;\n        return false;\n    }\n\n    // No baseDir: candidate returned unchanged so the source resolves it against its own default\n    // (process.cwd() on Node). Resolution goes through the source to keep this class node-free.\n    protected static resolveAgainstBase(candidate: string): string {\n        const baseDir = EnvapterBase._baseDir;\n        if (baseDir === undefined) return candidate;\n        const source = EnvapterBase._source;\n        /* v8 ignore next -- @preserve callers are all file-gated, so the source is never bare here */\n        if (!source.supportsFiles) return candidate;\n        return source.resolvePath(baseDir, candidate);\n    }\n\n    // File-based config (envPaths/baseDir/configureProfiles) is meaningless without a filesystem;\n    // throw instead of silently ignoring it on the browser or Workers. Narrows the source so callers\n    // can reach the file capabilities (resolvePath/normalizeBaseDir) after the check.\n    protected static assertFileApiSupported(api: string, source: EnvSource): asserts source is FileEnvSource {\n        if (!source.supportsFiles) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.FileApiUnsupported,\n                `${api} requires a filesystem-backed source; the bound source does not support .env files.`\n            );\n        }\n    }\n\n    // Existence via the bound source instead of fs.existsSync/accessSync: a file \"exists\" when the\n    // source can read it.\n    protected static sourceFileExists(path: string): boolean {\n        const source = EnvapterBase._source;\n        /* v8 ignore next -- @preserve every caller is file-gated, so this never sees a bare source */\n        if (!source.supportsFiles) return false;\n        return source.readFile(path, 'utf8') !== undefined;\n    }\n\n    protected static refreshCache(): void {\n        EnvaptCache.clear();\n        EnvapterBase._dotenvAddedKeys = new Set();\n        debugVerbose('cache cleared, reloading config');\n        void this.config; // getter rebuilds the cache as a side effect\n    }\n\n    protected static mirrorToProcessEnv(): void {\n        if (EnvapterBase._dotenvAddedKeys.size === 0) return;\n        const source = EnvapterBase._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 EnvapterBase._dotenvAddedKeys) {\n            const value = EnvaptCache.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] = value;\n            debugVerbose(`mirrored ${key} to the ambient environment`);\n        }\n        source.writeVars(mirrored);\n        debugVerbose(`mirrored ${EnvapterBase._dotenvAddedKeys.size} keys to the ambient environment`);\n    }\n\n    // Default returns the explicit `_envPaths`; EnvironmentMethods overrides to layer the dotenv-flow\n    // cascade + configureProfiles when envPaths was never explicitly set.\n    protected static resolveEffectivePaths(): string[] {\n        /* v8 ignore next -- @preserve */\n        return this._envPaths.map((p) => this.resolveAgainstBase(p));\n    }\n\n    protected static resolveKeyInput(keyInput: EnvKeyInput): { key: string; value: string | undefined } {\n        const keys = Array.isArray(keyInput) ? keyInput : [keyInput];\n        const normalizedKeys = keys as readonly string[];\n\n        if (normalizedKeys.length === 0) {\n            throw new EnvaptError(EnvaptErrorCodes.InvalidKeyInput, 'At least one environment key must be provided.');\n        }\n\n        if (normalizedKeys.some((k) => typeof k !== 'string')) {\n            throw new EnvaptError(EnvaptErrorCodes.InvalidKeyInput, 'Environment keys must be strings.');\n        }\n\n        if (normalizedKeys.some((k) => k.trim() === '')) {\n            throw new EnvaptError(EnvaptErrorCodes.InvalidKeyInput, 'Environment keys cannot be empty strings.');\n        }\n\n        for (const candidate of normalizedKeys) {\n            const value = this.config.get(candidate) as string | undefined;\n            if (value !== undefined) {\n                return { key: candidate, value };\n            }\n        }\n\n        return { key: normalizedKeys[0] as string, value: undefined };\n    }\n\n    protected static get config(): Map<string, unknown> {\n        if (EnvaptCache.size === 0) {\n            const source = EnvapterBase._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\n            // .env cascade, profiles, and envPaths; only the readVars() snapshot populates the cache.\n            if (source.supportsFiles) {\n                // Outside the try below so a missing configured profile path surfaces its EnvaptError; only dotenv parse errors stay caught.\n                const effectivePaths = this.resolveEffectivePaths();\n                debugVerbose(\n                    `effective .env paths: ${effectivePaths.length === 0 ? '(none)' : effectivePaths.join(', ')}`\n                );\n                try {\n                    added = loadDotenv({\n                        ...this._userDefinedEnvFileOptions,\n                        path: effectivePaths,\n                        processEnv: isolatedEnv,\n                        readFile: source.readFile.bind(source)\n                    });\n                } catch {}\n            }\n            EnvapterBase._dotenvAddedKeys = added;\n            for (const [key, value] of Object.entries(isolatedEnv)) EnvaptCache.set(key, value);\n            debugVerbose(`cache populated: ${EnvaptCache.size} keys total`);\n            if (EnvapterBase._syncProcessEnv) this.mirrorToProcessEnv();\n        }\n\n        return EnvaptCache;\n    }\n\n    /**\n     * Eagerly load the `.env` cascade now instead of lazily on the first read. Idempotent: a no-op\n     * once the cache is built. Useful before mirroring to `process.env` (see {@link syncProcessEnv}),\n     * which is what the `envapt/config` side-effect entry does.\n     */\n    static load(): void {\n        void this.config;\n    }\n\n    /**\n     * Bind the environment {@link EnvSource}. On Node the entry binds {@link NodeEnvSource} for you\n     * (a `process.env` snapshot plus the `.env` cascade); on the browser or Workers, pass a\n     * `ManualEnvSource` / `WorkerEnvSource` (or any `EnvSource`) before reading. Clears and rebuilds\n     * the cache.\n     */\n    static useSource(source: EnvSource): void {\n        EnvapterBase._source = source;\n        bindRuntimeFromSource(source);\n        this.refreshCache();\n    }\n\n    /**\n     * Read an environment variable as its raw string, skipping parsing and conversion.\n     */\n    getRaw(key: EnvKeyInput): string | undefined {\n        return EnvapterBase.resolveKeyInput(key).value;\n    }\n}\n"],"mappings":"6LAYa,EAAc,IAAI,IAG/B,IAAsB,EAAtB,MAAsB,CAAa,CAC/B,OAAiB,UAAsB,CAAC,MAAM,EAC9C,OAAiB,uBAAyB,GAC1C,OAAiB,SAA+B,IAAA,GAChD,OAAiB,2BAA6C,CAAC,EAC/D,OAAiB,QAAU,GAC3B,OAAiB,gBAAkB,GAEnC,OAAiB,iBAAgC,IAAI,IAGrD,OAAiB,QAAqB,IAAIA,EAAAA,iBAM1C,WAAW,OAAO,EAAgB,CAE9B,EAAa,QAAU,EAEvB,KAAK,aAAa,CACtB,CAEA,WAAW,QAAkB,CACzB,OAAO,EAAa,OACxB,CAOA,WAAW,MAAM,EAAmB,CAChC,EAAA,cAAc,CAAK,CACvB,CAEA,WAAW,OAAoB,CAC3B,OAAOC,EAAAA,cAAc,CACzB,CAaA,WAAW,eAAe,EAAgB,CACtC,EAAA,UAAU,uBAAuB,CAAK,EACtC,IAAM,EAAW,EAAa,gBAE9B,EAAa,gBAAkB,EAC3B,CAAC,GAAY,GAAS,EAAY,KAAO,GAAG,KAAK,mBAAmB,CAC5E,CAEA,WAAW,gBAA0B,CACjC,OAAO,EAAa,eACxB,CAEA,OAAiB,eAAe,EAAoC,CAGhE,MADA,GADI,IAAU,IAAA,IAAa,IAAU,IACjC,EAAa,SAAW,EAAM,KAAK,IAAM,GAEjD,CAIA,OAAiB,mBAAmB,EAA2B,CAC3D,IAAM,EAAU,EAAa,SAC7B,GAAI,IAAY,IAAA,GAAW,OAAO,EAClC,IAAM,EAAS,EAAa,QAG5B,OADK,EAAO,cACL,EAAO,YAAY,EAAS,CAAS,EADV,CAEtC,CAKA,OAAiB,uBAAuB,EAAa,EAAoD,CACrG,GAAI,CAAC,EAAO,cACR,MAAM,IAAIC,EAAAA,YAAAA,IAEN,GAAG,EAAI,oFACX,CAER,CAIA,OAAiB,iBAAiB,EAAuB,CACrD,IAAM,EAAS,EAAa,QAG5B,OADK,EAAO,cACL,EAAO,SAAS,EAAM,MAAM,IAAM,IAAA,GADP,EAEtC,CAEA,OAAiB,cAAqB,CAClC,EAAY,MAAM,EAClB,EAAa,iBAAmB,IAAI,IACpC,EAAA,aAAa,iCAAiC,EAC9C,KAAU,MACd,CAEA,OAAiB,oBAA2B,CACxC,GAAI,EAAa,iBAAiB,OAAS,EAAG,OAC9C,IAAM,EAAS,EAAa,QAE5B,GAAI,CAAC,EAAO,cAAe,OAC3B,IAAM,EAAmC,CAAC,EAC1C,IAAK,IAAM,KAAO,EAAa,iBAAkB,CAC7C,IAAM,EAAQ,EAAY,IAAI,CAAG,EAE7B,OAAO,GAAU,WACrB,EAAS,GAAO,EAChB,EAAA,aAAa,YAAY,EAAI,4BAA4B,EAC7D,CACA,EAAO,UAAU,CAAQ,EACzB,EAAA,aAAa,YAAY,EAAa,iBAAiB,KAAK,iCAAiC,CACjG,CAIA,OAAiB,uBAAkC,CAE/C,OAAO,KAAK,UAAU,IAAK,GAAM,KAAK,mBAAmB,CAAC,CAAC,CAC/D,CAEA,OAAiB,gBAAgB,EAAmE,CAEhG,IAAM,EADO,MAAM,QAAQ,CAAQ,EAAI,EAAW,CAAC,CAAQ,EAG3D,GAAI,EAAe,SAAW,EAC1B,MAAM,IAAIA,EAAAA,YAAAA,IAA8C,gDAAgD,EAG5G,GAAI,EAAe,KAAM,GAAM,OAAO,GAAM,QAAQ,EAChD,MAAM,IAAIA,EAAAA,YAAAA,IAA8C,mCAAmC,EAG/F,GAAI,EAAe,KAAM,GAAM,EAAE,KAAK,IAAM,EAAE,EAC1C,MAAM,IAAIA,EAAAA,YAAAA,IAA8C,2CAA2C,EAGvG,IAAK,IAAM,KAAa,EAAgB,CACpC,IAAM,EAAQ,KAAK,OAAO,IAAI,CAAS,EACvC,GAAI,IAAU,IAAA,GACV,MAAO,CAAE,IAAK,EAAW,OAAM,CAEvC,CAEA,MAAO,CAAE,IAAK,EAAe,GAAc,MAAO,IAAA,EAAU,CAChE,CAEA,WAAqB,QAA+B,CAChD,GAAI,EAAY,OAAS,EAAG,CACxB,IAAM,EAAS,EAAa,QAEtB,EAAsC,CAAE,GAAG,EAAO,SAAS,CAAE,EAE/D,EAAQ,IAAI,IAGhB,GAAI,EAAO,cAAe,CAEtB,IAAM,EAAiB,KAAK,sBAAsB,EAClD,EAAA,aACI,yBAAyB,EAAe,SAAW,EAAI,SAAW,EAAe,KAAK,IAAI,GAC9F,EACA,GAAI,CACA,EAAQC,EAAAA,WAAW,CACf,GAAG,KAAK,2BACR,KAAM,EACN,WAAY,EACZ,SAAU,EAAO,SAAS,KAAK,CAAM,CACzC,CAAC,CACL,MAAQ,CAAC,CACb,CACA,EAAa,iBAAmB,EAChC,IAAK,GAAM,CAAC,EAAK,KAAU,OAAO,QAAQ,CAAW,EAAG,EAAY,IAAI,EAAK,CAAK,EAClF,EAAA,aAAa,oBAAoB,EAAY,KAAK,YAAY,EAC1D,EAAa,iBAAiB,KAAK,mBAAmB,CAC9D,CAEA,OAAO,CACX,CAOA,OAAO,MAAa,CAChB,KAAU,MACd,CAQA,OAAO,UAAU,EAAyB,CACtC,EAAa,QAAU,EACvB,EAAA,sBAAsB,CAAM,EAC5B,KAAK,aAAa,CACtB,CAKA,OAAO,EAAsC,CACzC,OAAO,EAAa,gBAAgB,CAAG,EAAE,KAC7C,CACJ"}