envapt 5.2.0 → 6.0.1

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

@@ -1 +1 @@
-{"version":3,"file":"BuiltInConverters.mjs","names":["converter"],"sources":["../../../src/converters/BuiltInConverters.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/unbound-method */\n\nimport { EnvaptError, EnvaptErrorCodes } from '../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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"}
+{"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":"2CAcA,MAAM,EAAgB,IAKhB,EAAgB,GAAqB,EACrC,EAAc,GAAmB,EACjC,EAAa,GAAgB,EAG7B,EAAyC,CAC3C,GAAI,EACJ,EAAG,EACH,EAAG,EACH,EAAG,EACH,EAAG,EACH,EARgB,EAAgB,CASpC,EAEM,EAAgB,IAAI,OAAO,OAAO,GAAG,mCAAoC,GAAG,EAC5E,EAAiB,IAAI,OAAO,OAAO,GAAG,kCAAmC,GAAG,EAWlF,SAAS,EAAgB,EAAe,EAAS,GAA2B,CACxE,IAAM,EAAQ,EAAM,MAAM,EAAS,EAAiB,CAAa,EACjE,GAAI,CAAC,EAAO,OAEZ,GAAM,EAAG,EAAQ,GAAgB,EACjC,GAAI,CAAC,EAAQ,OAEb,IAAM,EAAQ,OAAO,WAAW,CAAM,EAClC,WAAO,MAAM,CAAK,EAGtB,OAAO,EAAQ,EADD,GAAgB,KAElC,CAOA,IAAa,EAAb,MAAa,CAAkB,CAC3B,OAAO,OAAO,EAAa,EAAwC,CAC/D,OAAO,OAAO,CAAG,CACrB,CAEA,OAAO,OAAO,EAAa,EAAuC,CAC9D,IAAM,EAAS,OAAO,CAAG,EACzB,OAAO,OAAO,MAAM,CAAM,EAAI,EAAW,CAC7C,CAEA,OAAO,QAAQ,EAAa,EAAyC,CACjE,IAAM,EAAQ,EAAI,YAAY,CAAC,CAAC,KAAK,EAOrC,MAFI,CAHkB,IAAK,MAAO,OAAQ,IAGtC,CAAA,CAAa,SAAS,CAAK,EAAU,GACrC,CAHiB,IAAK,KAAM,QAAS,KAGrC,CAAA,CAAY,SAAS,CAAK,EAAU,GACjC,CACX,CAEA,OAAO,OAAO,EAAa,EAAuC,CAC9D,GAAI,CACA,OAAO,OAAO,CAAG,CACrB,MAAQ,CACJ,OAAO,CACX,CACJ,CAEA,OAAO,OAAO,EAAa,EAAuC,CAC9D,GAAI,CACA,OAAO,EAAM,OAAO,IAAI,CAAG,EAAI,CACnC,MAAQ,CACJ,OAAO,CACX,CACJ,CAEA,OAAO,QAAQ,EAAa,EAAuC,CAC/D,IAAM,EAAS,OAAO,SAAS,EAAK,EAAE,EACtC,OAAO,OAAO,MAAM,CAAM,EAAI,EAAW,CAC7C,CAEA,OAAO,MAAM,EAAa,EAAuC,CAC7D,IAAM,EAAS,OAAO,WAAW,CAAG,EACpC,OAAO,OAAO,MAAM,CAAM,EAAI,EAAW,CAC7C,CAEA,OAAO,KAAK,EAAa,EAA6C,CAClE,GAAI,CACA,OAAO,KAAK,MAAM,CAAG,CACzB,MAAQ,CACJ,OAAO,CACX,CACJ,CAEA,OAAO,IAAI,EAAa,EAAiC,CACrD,GAAI,CACA,OAAO,IAAI,IAAI,CAAG,CACtB,MAAQ,CACJ,OAAO,CACX,CACJ,CAEA,OAAO,OAAO,EAAa,EAAuC,CAC9D,GAAI,CAEA,IAAM,EAAQ,EAAI,MAAM,IAAI,OAAO,OAAO,GAAG,wBAAwB,CAAC,EAGtE,OAFI,EAAc,IAAI,OAAO,EAAM,GAAc,EAAM,EAAE,EAElD,IAAI,OAAO,CAAG,CACzB,MAAQ,CACJ,OAAO,CACX,CACJ,CAEA,OAAO,KAAK,EAAa,EAAmC,CAExD,GAAI,IAAI,OAAO,OAAO,GAAG,OAAO,CAAC,CAAC,KAAK,CAAG,EAAG,CAEzC,IAAM,EAAS,IAAI,KADD,SAAS,EAAK,EACA,CAAC,EACjC,OAAO,OAAO,MAAM,EAAO,QAAQ,CAAC,EAAI,EAAW,CACvD,CAIA,GAAI,CAAC,IADgB,OAAO,OAAO,GAAG,mDAAoD,GAC9E,CAAC,CAAC,KAAK,CAAG,EAAG,OAAO,EAEhC,IAAM,EAAS,IAAI,KAAK,CAAG,EAC3B,OAAO,OAAO,MAAM,EAAO,QAAQ,CAAC,EAAI,EAAW,CACvD,CAEA,OAAO,KAAK,EAAa,EAA6C,CAClE,IAAM,EAAY,EAAgB,CAAG,EACrC,GAAI,IAAc,IAAA,GAAW,OAAO,EAGpC,GAAI,OAAO,GAAa,SAAU,OAAO,EACzC,GAAI,OAAO,GAAa,SAAU,CAE9B,IAAM,EAAiB,EAAgB,EAAU,EAAI,EACrD,GAAI,IAAmB,IAAA,GACnB,MAAM,IAAI,EAAA,IAEN,yBAAyB,EAAS,0FACtC,EAEJ,OAAO,CACX,CAEJ,CAeA,OAAO,sBAAsB,EAAa,EAAiB,EAAS,GAAkB,CAClF,GAAI,EAAI,KAAK,IAAM,GAAI,MAAO,CAAC,EAE/B,IAAM,EAAe,EAAI,MAAM,EAAO,SAAS,CAAC,CAAC,IAAK,GAAS,OAAO,CAAI,CAAC,CAAC,KAAK,CAAC,EAElF,GAAI,EAAQ,CACR,IAAM,EAAW,EAAa,UAAW,GAAS,IAAS,EAAE,EAC7D,GAAI,IAAa,GACb,MAAM,IAAI,EAAA,IAEN,0BAA0B,EAAS,4CACvC,CAER,CAEA,IAAM,EAAQ,EAAa,OAAO,OAAO,EAEzC,GAAI,CAAC,EAAM,OAAQ,MAAO,CAAC,EAE3B,IAAM,EAAY,EAAO,GAEzB,GAAI,OAAO,GAAc,WACrB,OAAO,EAAM,KAAK,EAAM,IAAU,CAE9B,IAAM,EAASA,EAAU,CAAI,EAC7B,GAAI,IAAW,IAAA,GACX,MAAM,IAAI,EAAA,IAEN,yDAAyD,EAAK,aAAa,EAAM,EACrF,EAEJ,OAAO,CACX,CAAC,EAGL,IAAM,EAAY,EAAkB,aAAa,CAAS,EAC1D,OAAO,EAAM,KAAK,EAAM,IAAU,CAC9B,IAAM,EAAY,EAAU,EAAM,IAAA,EAAS,EAC3C,GAAI,IAAc,IAAA,GACd,MAAM,IAAI,EAAA,IAEN,YAAY,EAAK,aAAa,EAAM,6BAA6B,EAAU,EAC/E,EAEJ,OAAO,CACX,CAAC,CACL,CAKA,OAAO,aAAiD,EAA2C,CAgB/F,MAAO,CAdH,OAAQ,EAAkB,OAC1B,OAAQ,EAAkB,OAC1B,QAAS,EAAkB,QAC3B,QAAS,EAAkB,QAC3B,OAAQ,EAAkB,OAC1B,OAAQ,EAAkB,OAC1B,MAAO,EAAkB,MACzB,KAAM,EAAkB,KACxB,IAAK,EAAkB,IACvB,OAAQ,EAAkB,OAC1B,KAAM,EAAkB,KACxB,KAAM,EAAkB,IAGZ,EAAE,EACtB,CACJ"}

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

@@ -1 +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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"}
+{"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/workerd/core/EnvapterBase.mjs.map

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

package/dist/workerd/core/EnvironmentMethods.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"EnvironmentMethods.mjs","names":[],"sources":["../../../src/core/EnvironmentMethods.ts"],"sourcesContent":["import { debugWarn } from '../Debug';\nimport { EnvaptError, EnvaptErrorCodes } from '../Error';\nimport { EnvapterBase } from './EnvapterBase';\n\nimport type { EnvProfile, ProfilesConfig } from '../types';\n\n/**\n * Environment types supported by Envapter\n * @public\n */\nexport enum Environment {\n    Development,\n    Staging,\n    Production,\n    Test\n}\n\n// Keys carrying the environment name, highest precedence first. Checked in order until the first with a non-empty value is found, or defaulting to development if none are set.\nconst ENV_KEYS = ['ENVIRONMENT', 'ENV', 'NODE_ENV', 'MODE'] as const;\n\nfunction parseEnvironment(raw: string): Environment | undefined {\n    switch (raw.toLowerCase()) {\n        case 'production':\n            return Environment.Production;\n        case 'staging':\n            return Environment.Staging;\n        case 'test':\n            return Environment.Test;\n        case 'development':\n            return Environment.Development;\n        default:\n            return undefined;\n    }\n}\n\n/**\n * Mixin for environment detection and checking methods\n * @internal\n */\nexport class EnvironmentMethods extends EnvapterBase {\n    protected static _environment: Environment | undefined;\n    protected static _environmentExplicitlySet = false;\n    protected static _profiles: ProfilesConfig | undefined;\n\n    protected static determineEnvironment(env?: string | Environment): void {\n        if (typeof env === 'number') {\n            this._environment = env;\n            this._environmentExplicitlySet = true;\n            return;\n        }\n        if (typeof env === 'string') {\n            this._environment = parseEnvironment(env) ?? Environment.Development;\n            this._environmentExplicitlySet = true;\n            return;\n        }\n\n        const raw = this.firstEnvKeyValue((key) => {\n            const value = this.config.get(key);\n            return typeof value === 'string' ? value : undefined;\n        });\n        if (raw === undefined) {\n            debugWarn(`no environment set (looked for ${ENV_KEYS.join(', ')}); defaulting to development`);\n            this._environment = Environment.Development;\n            return;\n        }\n        const parsed = parseEnvironment(raw);\n        if (parsed === undefined) {\n            debugWarn(`unrecognized environment \"${raw}\"; defaulting to development`);\n            this._environment = Environment.Development;\n            return;\n        }\n        this._environment = parsed;\n    }\n\n    private static firstEnvKeyValue(read: (key: string) => string | undefined): string | undefined {\n        for (const key of ENV_KEYS) {\n            const value = read(key);\n            if (value !== undefined && value.length > 0) return value;\n        }\n        return undefined;\n    }\n\n    /**\n     * Get the current application environment\n     */\n    static get environment(): Environment {\n        if (this._environment === undefined) {\n            this.determineEnvironment();\n        }\n        return this._environment as Environment;\n    }\n\n    /**\n     * Set the application environment. Accepts either Environment enum or string value.\n     */\n    static set environment(env: string | Environment) {\n        this.determineEnvironment(env);\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.environment}\n     */\n    get environment(): Environment {\n        return EnvironmentMethods.environment;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.environment}\n     */\n    set environment(env: string | Environment) {\n        EnvironmentMethods.determineEnvironment(env);\n    }\n\n    /**\n     * Check if the current environment is production\n     */\n    static get isProduction(): boolean {\n        return this.environment === Environment.Production;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.isProduction}\n     */\n    get isProduction(): boolean {\n        return EnvironmentMethods.environment === Environment.Production;\n    }\n\n    /**\n     * Check if the current environment is staging\n     */\n    static get isStaging(): boolean {\n        return this.environment === Environment.Staging;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.isStaging}\n     */\n    get isStaging(): boolean {\n        return EnvironmentMethods.environment === Environment.Staging;\n    }\n\n    /**\n     * Check if the current environment is development\n     */\n    static get isDevelopment(): boolean {\n        return this.environment === Environment.Development;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.isDevelopment}\n     */\n    get isDevelopment(): boolean {\n        return EnvironmentMethods.environment === Environment.Development;\n    }\n\n    /**\n     * Check if the current environment is test\n     */\n    static get isTest(): boolean {\n        return this.environment === Environment.Test;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.isTest}\n     */\n    get isTest(): boolean {\n        return EnvironmentMethods.environment === Environment.Test;\n    }\n\n    protected static override refreshCache(): void {\n        // If the env was inferred (not user-set), reset it so re-hydration re-determines\n        // from current state. If the user explicitly set Envapter.environment = X, preserve\n        // that value through the refresh. The immediate re-hydration inside super.refreshCache()\n        // will use it for cascade selection.\n        if (!this._environmentExplicitlySet) this._environment = undefined;\n        super.refreshCache();\n    }\n\n    /**\n     * Reads the source's raw vars (not `this.config`, which would recurse: cascade selection runs\n     * before the `.env` load). `Envapter.environment` may differ post-load if a file sets `ENVIRONMENT`.\n     * @internal\n     */\n    protected static getCascadeEnvironment(): Environment {\n        if (this._environment !== undefined) return this._environment;\n\n        const vars = EnvapterBase._source.readVars();\n        const raw = this.firstEnvKeyValue((key) => vars[key]);\n        return raw === undefined ? Environment.Development : (parseEnvironment(raw) ?? Environment.Development);\n    }\n\n    /**\n     * Build the dotenv-flow cascade for a given environment, in dotenv first-wins precedence\n     * order (highest precedence first). Missing files are silently filtered.\n     *\n     * Precedence is **most-specific-wins** (matches Vite / Astro / Vocs):\n     *   `.env.${env}.local` \\> `.env.${env}` \\> `.env.local` \\> `.env`\n     *\n     * This differs from dotenv-flow / Next.js convention which puts `.env.local` above\n     * `.env.${env}`. We chose the most-specific-wins order so committed env-specific files\n     * (`.env.production`) are authoritative for that environment regardless of whether a\n     * stray `.env.local` is present.\n     * @internal\n     */\n    protected static buildCascadePaths(env: Environment): string[] {\n        const envName = Environment[env].toLowerCase();\n        return [`.env.${envName}.local`, `.env.${envName}`, '.env.local', '.env']\n            .map((name) => this.resolveAgainstBase(name))\n            .filter((p) => this.sourceFileExists(p));\n    }\n\n    private static normalizeProfilePaths(profile: EnvProfile | undefined): string[] {\n        if (!profile) return [];\n        return Array.isArray(profile.paths) ? profile.paths : [profile.paths];\n    }\n\n    /**\n     * Override the base implementation to layer the dotenv-flow cascade + any\n     * `Envapter.configureProfiles` overrides on top of `_envPaths` when the user has NOT\n     * explicitly set `envPaths`.\n     *\n     * Precedence (passed to dotenv with first-wins semantics):\n     *   1. profile-configured paths for the current env (if any)\n     *   2. `.env.${env}.local`\n     *   3. `.env.${env}`\n     *   4. `.env.local`\n     *   5. `.env`\n     *\n     * If `useDefaults: false` is set on the profiles config, only (1) is loaded, no cascade.\n     * If `envPaths` was explicitly set, only `envPaths` is loaded (everything else ignored).\n     * @internal\n     */\n    protected static override resolveEffectivePaths(): string[] {\n        if (this._envPathsExplicitlySet) return this._envPaths.map((p) => this.resolveAgainstBase(p));\n\n        const env = this.getCascadeEnvironment();\n        const profileEntry = this._profiles?.[env];\n        const profilePaths = this.normalizeProfilePaths(profileEntry);\n\n        // Validate that explicitly configured profile paths exist for the active env.\n        if (profilePaths.length > 0) {\n            const missing = profilePaths.filter((p) => !this.sourceFileExists(this.resolveAgainstBase(p)));\n            if (missing.length > 0) {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.EnvFilesNotFound,\n                    `Environment file not found at path: ${missing.join(', ')}`\n                );\n            }\n        }\n\n        const cascade = this._profiles?.useDefaults === false ? [] : this.buildCascadePaths(env);\n        return [...profilePaths.map((p) => this.resolveAgainstBase(p)), ...cascade];\n    }\n}\n"],"mappings":"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"}
+{"version":3,"file":"EnvironmentMethods.mjs","names":[],"sources":["../../../src/core/EnvironmentMethods.ts"],"sourcesContent":["import { debugWarn } from '../Debug';\nimport { EnvaptError, EnvaptErrorCodes } from '../Error';\nimport { EnvapterBase } from './EnvapterBase';\n\nimport type { EnvProfile, ProfilesConfig } from '../types';\n\n/**\n * Environment types supported by Envapter\n * @public\n */\nexport enum Environment {\n    Development,\n    Staging,\n    Production,\n    Test\n}\n\n// Keys carrying the environment name, highest precedence first. Checked in order until the first with a non-empty value is found, or defaulting to development if none are set.\nconst ENV_KEYS = ['ENVIRONMENT', 'ENV', 'NODE_ENV', 'MODE'] as const;\n\nfunction parseEnvironment(raw: string): Environment | undefined {\n    switch (raw.toLowerCase()) {\n        case 'production':\n            return Environment.Production;\n        case 'staging':\n            return Environment.Staging;\n        case 'test':\n            return Environment.Test;\n        case 'development':\n            return Environment.Development;\n        default:\n            return undefined;\n    }\n}\n\n/**\n * Mixin for environment detection and checking methods\n * @internal\n */\nexport class EnvironmentMethods extends EnvapterBase {\n    protected static _environment: Environment | undefined;\n    protected static _environmentExplicitlySet = false;\n    protected static _profiles: ProfilesConfig | undefined;\n\n    protected static determineEnvironment(env?: string | Environment): void {\n        if (typeof env === 'number') {\n            this._environment = env;\n            this._environmentExplicitlySet = true;\n            return;\n        }\n        if (typeof env === 'string') {\n            this._environment = parseEnvironment(env) ?? Environment.Development;\n            this._environmentExplicitlySet = true;\n            return;\n        }\n\n        const raw = this.firstEnvKeyValue((key) => {\n            const value = this.config.get(key);\n            return typeof value === 'string' ? value : undefined;\n        });\n        if (raw === undefined) {\n            debugWarn(`no environment set (looked for ${ENV_KEYS.join(', ')}); defaulting to development`);\n            this._environment = Environment.Development;\n            return;\n        }\n        const parsed = parseEnvironment(raw);\n        if (parsed === undefined) {\n            debugWarn(`unrecognized environment \"${raw}\"; defaulting to development`);\n            this._environment = Environment.Development;\n            return;\n        }\n        this._environment = parsed;\n    }\n\n    private static firstEnvKeyValue(read: (key: string) => string | undefined): string | undefined {\n        for (const key of ENV_KEYS) {\n            const value = read(key);\n            if (value !== undefined && value.length > 0) return value;\n        }\n        return undefined;\n    }\n\n    /**\n     * Get the current application environment\n     */\n    static get environment(): Environment {\n        if (this._environment === undefined) {\n            this.determineEnvironment();\n        }\n        return this._environment as Environment;\n    }\n\n    /**\n     * Set the application environment. Accepts either Environment enum or string value.\n     */\n    static set environment(env: string | Environment) {\n        this.determineEnvironment(env);\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.environment}\n     */\n    get environment(): Environment {\n        return EnvironmentMethods.environment;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.environment}\n     */\n    set environment(env: string | Environment) {\n        EnvironmentMethods.determineEnvironment(env);\n    }\n\n    /**\n     * Check if the current environment is production\n     */\n    static get isProduction(): boolean {\n        return this.environment === Environment.Production;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.isProduction}\n     */\n    get isProduction(): boolean {\n        return EnvironmentMethods.environment === Environment.Production;\n    }\n\n    /**\n     * Check if the current environment is staging\n     */\n    static get isStaging(): boolean {\n        return this.environment === Environment.Staging;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.isStaging}\n     */\n    get isStaging(): boolean {\n        return EnvironmentMethods.environment === Environment.Staging;\n    }\n\n    /**\n     * Check if the current environment is development\n     */\n    static get isDevelopment(): boolean {\n        return this.environment === Environment.Development;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.isDevelopment}\n     */\n    get isDevelopment(): boolean {\n        return EnvironmentMethods.environment === Environment.Development;\n    }\n\n    /**\n     * Check if the current environment is test\n     */\n    static get isTest(): boolean {\n        return this.environment === Environment.Test;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.isTest}\n     */\n    get isTest(): boolean {\n        return EnvironmentMethods.environment === Environment.Test;\n    }\n\n    protected static override refreshCache(): void {\n        // If the env was inferred (not user-set), reset it so re-hydration re-determines\n        // from current state. If the user explicitly set Envapter.environment = X, preserve\n        // that value through the refresh. The immediate re-hydration inside super.refreshCache()\n        // will use it for cascade selection.\n        if (!this._environmentExplicitlySet) this._environment = undefined;\n        super.refreshCache();\n    }\n\n    /**\n     * Reads the source's raw vars (not `this.config`, which would recurse: cascade selection runs\n     * before the `.env` load). `Envapter.environment` may differ post-load if a file sets `ENVIRONMENT`.\n     * @internal\n     */\n    protected static getCascadeEnvironment(): Environment {\n        if (this._environment !== undefined) return this._environment;\n\n        const vars = EnvapterBase._source.readVars();\n        const raw = this.firstEnvKeyValue((key) => vars[key]);\n        return raw === undefined ? Environment.Development : (parseEnvironment(raw) ?? Environment.Development);\n    }\n\n    /**\n     * Build the dotenv-flow cascade for a given environment, in dotenv first-wins precedence\n     * order (highest precedence first). Missing files are silently filtered.\n     *\n     * Precedence is **most-specific-wins** (matches Vite / Astro / Vocs):\n     *   `.env.${env}.local` \\> `.env.${env}` \\> `.env.local` \\> `.env`\n     *\n     * This differs from dotenv-flow / Next.js convention which puts `.env.local` above\n     * `.env.${env}`. We chose the most-specific-wins order so committed env-specific files\n     * (`.env.production`) are authoritative for that environment regardless of whether a\n     * stray `.env.local` is present.\n     * @internal\n     */\n    protected static buildCascadePaths(env: Environment): string[] {\n        const envName = Environment[env].toLowerCase();\n        return [`.env.${envName}.local`, `.env.${envName}`, '.env.local', '.env']\n            .map((name) => this.resolveAgainstBase(name))\n            .filter((p) => this.sourceFileExists(p));\n    }\n\n    private static normalizeProfilePaths(profile: EnvProfile | undefined): string[] {\n        if (!profile) return [];\n        return Array.isArray(profile.paths) ? profile.paths : [profile.paths];\n    }\n\n    /**\n     * Override the base implementation to layer the dotenv-flow cascade + any\n     * `Envapter.configureProfiles` overrides on top of `_envPaths` when the user has NOT\n     * explicitly set `envPaths`.\n     *\n     * Precedence (passed to dotenv with first-wins semantics):\n     *   1. profile-configured paths for the current env (if any)\n     *   2. `.env.${env}.local`\n     *   3. `.env.${env}`\n     *   4. `.env.local`\n     *   5. `.env`\n     *\n     * If `useDefaults: false` is set on the profiles config, only (1) is loaded, no cascade.\n     * If `envPaths` was explicitly set, only `envPaths` is loaded (everything else ignored).\n     * @internal\n     */\n    protected static override resolveEffectivePaths(): string[] {\n        if (this._envPathsExplicitlySet) return this._envPaths.map((p) => this.resolveAgainstBase(p));\n\n        const env = this.getCascadeEnvironment();\n        const profileEntry = this._profiles?.[env];\n        const profilePaths = this.normalizeProfilePaths(profileEntry);\n\n        // Validate that explicitly configured profile paths exist for the active env.\n        if (profilePaths.length > 0) {\n            const missing = profilePaths.filter((p) => !this.sourceFileExists(this.resolveAgainstBase(p)));\n            if (missing.length > 0) {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.EnvFilesNotFound,\n                    `Environment file not found at path: ${missing.join(', ')}`\n                );\n            }\n        }\n\n        const cascade = this._profiles?.useDefaults === false ? [] : this.buildCascadePaths(env);\n        return [...profilePaths.map((p) => this.resolveAgainstBase(p)), ...cascade];\n    }\n}\n"],"mappings":"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"}

package/dist/workerd/decorators/Envapt.d.mts

@@ -1,5 +1,5 @@
 import { ArrayOf } from "../converters/Converters.mjs";
-import { BuiltInConverter, ConverterFunction, InferConverterFallbackType, InferPrimitiveFallbackType, InferPrimitiveReturnType, PrimitiveConstructor } from "../types/Conversion.mjs";
+import { BuiltInConverter, ConverterFunction, InferConverterFallbackType, InferPrimitiveReturnType, PrimitiveConstructor } from "../types/Conversion.mjs";
 import { InferSchemaOutput, StandardSchemaV1 } from "../StandardSchema.mjs";
 import { SchemaConstraint } from "../types/Schema.mjs";
 import { EnvKeyInput } from "../types/Env.mjs";
@@ -173,7 +173,7 @@ declare function Envapt(key: EnvKeyInput, options: {
   required: true;
 }): PropertyDecorator;
 /**
- * Classic API: No fallback
+ * No-fallback form. The property resolves from env or `null`.
  *
  * @param key - Environment variable name(s) to load
  * @public
@@ -187,31 +187,6 @@ declare function Envapt(key: EnvKeyInput, options: {
  * ```
  */
 declare function Envapt<_TReturnType = string | null>(key: EnvKeyInput): PropertyDecorator;
-/**
- * Classic API: Primitive fallback only
- *
- * @param key - Environment variable name(s) to load
- * @param fallback - Default primitive value
- * @param converter - Optional primitive constructor (String, Number, etc.)
- * @public
- * @deprecated - Use the options object: `@Envapt('KEY', { converter, fallback })`. The positional
- * form only accepts primitive constructors and cannot express built-in tokens, array/custom
- * converters, `schema`, or `required`. Deprecated in v5, removed in v6.
- * @example
- * ```ts
- * // Classic API with primitive fallback and optional primitive converter
- * class Config extends Envapter {
- *   // Provide fallback only
- *   \@Envapt('HOST', 'localhost')
- *   static readonly host: string;
- *
- *   // Provide fallback and converter
- *   \@Envapt('PORT', 8080, Number)
- *   static readonly port: number;
- * }
- * ```
- */
-declare function Envapt<TFallback extends string | number | boolean | bigint | symbol | undefined>(key: EnvKeyInput, fallback: InferPrimitiveFallbackType<TFallback>, converter?: PrimitiveConstructor): PropertyDecorator;
 /**
  * Usage 6: Standard Schema v1 adapter (zod, valibot, arktype, hand-rolled). Synchronous
  * schemas only; a Promise-returning `validate` triggers a runtime

package/dist/workerd/decorators/Envapt.mjs

@@ -1,2 +1,2 @@
-import{EnvaptError as e}from"../Error.mjs";import{Validator as t}from"../Validators.mjs";import{createPropertyDecorator as n}from"./createPropertyDecorator.mjs";function r(r,i,a){let o,s,c,l=!0,u=!1;if(i&&typeof i==`object`&&(`fallback`in i||`converter`in i||`required`in i||`schema`in i)){let n=i;if(o=n.fallback,s=n.converter,l=`fallback`in n,u=n.required===!0,u&&l&&o!==void 0)throw new e(302,"`required: true` and `fallback` are mutually exclusive on @Envapt options. Drop the fallback or call `Envapter.require()` separately.");if(`schema`in n&&n.schema!==void 0){if(!t.isStandardSchema(n.schema))throw new e(302,"`schema` must be a Standard Schema v1 object (zod, valibot, arktype, or any `~standard`-conformant value).");if(s!==void 0)throw new e(302,"`schema` and `converter` are mutually exclusive on @Envapt options. Drop one as they both turn a raw env string into a typed value.");c=n.schema}}else o=i,s=a,l=arguments.length>1;return n(r,{fallback:o,converter:s,hasFallback:l,required:u,schema:c})}export{r as Envapt};
+import{EnvaptError as e}from"../Error.mjs";import{Validator as t}from"../Validators.mjs";import{createPropertyDecorator as n}from"./createPropertyDecorator.mjs";function r(r,i){let a,o,s,c=!1,l=!1;if(i!==void 0){if(typeof i!=`object`||!i||!(`fallback`in i||`converter`in i||`required`in i||`schema`in i))throw new e(302,"The positional `@Envapt(key, fallback, converter)` form was removed in v6. Pass an options object instead, like `@Envapt(key, { converter, fallback })`, or use one of the sugar decorators.");let n=i;if(a=n.fallback,o=n.converter,c=`fallback`in n,l=n.required===!0,l&&c&&a!==void 0)throw new e(302,"`required: true` and `fallback` are mutually exclusive on @Envapt options. Drop the fallback or call `Envapter.require()` separately.");if(`schema`in n&&n.schema!==void 0){if(!t.isStandardSchema(n.schema))throw new e(302,"`schema` must be a Standard Schema v1 object (zod, valibot, arktype, or any `~standard`-conformant value).");if(o!==void 0)throw new e(302,"`schema` and `converter` are mutually exclusive on @Envapt options. Drop one as they both turn a raw env string into a typed value.");s=n.schema}}return n(r,{fallback:a,converter:o,hasFallback:c,required:l,schema:s})}export{r as Envapt};
 //# sourceMappingURL=Envapt.mjs.map

package/dist/workerd/decorators/Envapt.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"Envapt.mjs","names":[],"sources":["../../../src/decorators/Envapt.ts"],"sourcesContent":["import { createPropertyDecorator } from './createPropertyDecorator';\nimport { EnvaptError, EnvaptErrorCodes } from '../Error';\nimport { Validator } from '../Validators';\n\nimport type { ArrayOf } from '../converters';\nimport type { InferSchemaOutput, StandardSchemaV1 } from '../StandardSchema';\nimport type {\n    BuiltInConverter,\n    ConverterFunction,\n    EnvKeyInput,\n    EnvaptConverter,\n    EnvaptOptions,\n    InferConverterFallbackType,\n    InferPrimitiveFallbackType,\n    InferPrimitiveReturnType,\n    PrimitiveConstructor,\n    SchemaConstraint\n} from '../types';\n\n/**\n * Usage 1: Either a custom converter function + fallback (both required), OR a fallback\n * only (no converter).\n *\n * @param key - Environment variable name(s) to load\n * @param options - Configuration options\n * @public\n * @example\n * ```ts\n * class Config extends Envapter {\n *   // Custom converter that validates a non-empty API key\n *   \\@Envapt('API_KEY', {\n *     fallback: 'default-key',\n *     converter(raw, _fallback) {\n *       if (!raw || raw.trim() === '') throw new Error('API_KEY required');\n *       return raw.trim();\n *     }\n *   })\n *   static readonly apiKey: string;\n *\n *   // Fallback-only (no converter): string fallback\n *   \\@Envapt('LOG_FILE', { fallback: '/var/log/app.log' })\n *   static readonly logFile: string;\n *\n *   // Fallback-only: arbitrary object fallback\n *   \\@Envapt('RETRY_POLICY', { fallback: { retries: 3, backoff: 'exponential' } })\n *   static readonly retryPolicy: unknown;\n * }\n * ```\n */\nexport function Envapt<TFallback>(\n    key: EnvKeyInput,\n    options:\n        | { converter: (raw: string | undefined, fallback: TFallback) => TFallback; fallback: TFallback }\n        | { fallback: TFallback; converter?: undefined }\n): PropertyDecorator;\n\n/**\n * Usage 2: Custom converter function without fallback. Either omit `required` (returns the\n * converter's output, possibly `undefined`) or pass `required: true` to throw `MissingEnvValue`\n * on missing/empty values.\n *\n * @param key - Environment variable name(s) to load\n * @param options - Configuration options with custom converter only, with optional `required: true`\n * @public\n * @example\n * ```ts\n * class Config extends Envapter {\n *   \\@Envapt('FEATURE_FLAGS', { converter(raw) {\n *     return raw ? raw.split('|').map(s => s.trim()) : [];\n *   } })\n *   static readonly featureFlags: string[];\n *\n *   \\@Envapt('JWT_SECRET', {\n *     converter: (raw) => Buffer.from(raw ?? '', 'base64'),\n *     required: true\n *   })\n *   declare static readonly jwtSecret: Buffer;\n * }\n * ```\n */\nexport function Envapt<TReturnType>(\n    key: EnvKeyInput,\n    options:\n        | { converter: ConverterFunction<TReturnType>; required?: false }\n        | { converter: ConverterFunction<TReturnType>; required: true }\n): PropertyDecorator;\n\n/**\n * Usage 3: Built-in or array converter with optional fallback OR `required: true`.\n *\n * `InferConverterFallbackType` handles asymmetric cases: scalar `Converters.Time` accepts\n * `TimeFallback`, and `ArrayOf<'time'>` accepts `TimeFallback[]`. Every other converter\n * reduces to `InferConverterReturnType`. The two object-shape branches are mutually\n * exclusive: either provide a `fallback`, or pass `required: true` to throw\n * `MissingEnvValue` on missing/empty values.\n *\n * @param key - Environment variable name(s) to load\n * @param options - Configuration options\n * @public\n * @example\n * ```ts\n * import { Converters } from 'envapt';\n *\n * class Config extends Envapter {\n *   // Use built-in Number converter with a numeric fallback\n *   \\@Envapt('APP_PORT', { converter: Converters.Number, fallback: 3000 })\n *   static readonly port: number;\n *\n *   // Url converter: the fallback is a URL instance, not a string\n *   \\@Envapt('APP_URL', { converter: Converters.Url, fallback: new URL('http://localhost:3000') })\n *   static readonly url: URL;\n *\n *   // Prefer CANARY_URL when present, otherwise fall back to APP_URL\n *   \\@Envapt(['CANARY_URL', 'APP_URL'], { converter: Converters.Url })\n *   static readonly canaryUrl: URL | null;\n *\n *   // `Converters.Time` accepts either a number (milliseconds) or a time-string fallback (`<number><unit>`).\n *   \\@Envapt('REQUEST_TIMEOUT', { converter: Converters.Time, fallback: '10s' })\n *   static readonly requestTimeout: number;\n *\n *   // Array converter: comma-separated list of origins -> string[]\n *   \\@Envapt('ALLOWED_ORIGINS', {\n *     converter: Converters.array({ of: Converters.String }),\n *     fallback: ['https://example.com']\n *   })\n *   static readonly allowedOrigins: string[];\n *\n *   \\@Envapt('DATABASE_URL', { converter: Converters.Url, required: true })\n *   declare static readonly databaseUrl: URL;\n * }\n * ```\n */\nexport function Envapt<TConverter extends BuiltInConverter | ArrayOf>(\n    key: EnvKeyInput,\n    options:\n        | { converter: TConverter; fallback?: InferConverterFallbackType<TConverter> | undefined; required?: false }\n        | { converter: TConverter; required: true }\n): PropertyDecorator;\n\n/**\n * Usage 4: Primitive constructor with optional fallback\n *\n * @param key - Environment variable name(s) to load\n * @param options - Configuration options with primitive constructor\n * @public\n * @example\n * ```ts\n * // Use primitive constructors to coerce values\n * class Config extends Envapter {\n *   \\@Envapt('MAX_CONNECTIONS', { converter: Number, fallback: 100 })\n *   static readonly maxConnections: number;\n *\n *   \\@Envapt('FEATURE_ENABLED', { converter: Boolean, fallback: false })\n *   static readonly featureEnabled: boolean;\n * }\n * ```\n */\nexport function Envapt<TConstructor extends PrimitiveConstructor>(\n    key: EnvKeyInput,\n    options:\n        | { converter: TConstructor; fallback?: InferPrimitiveReturnType<TConstructor>; required?: false }\n        | { converter: TConstructor; required: true }\n): PropertyDecorator;\n\n/**\n * Usage 5: Required, no converter (raw string). Throws `MissingEnvValue` on first access if\n * the env value is missing or empty (post-trim). Independent of global `Envapter.strict`.\n * Combining `required: true` with `fallback` fails to match any overload at compile time;\n * the runtime Validator catches dynamic objects that bypass the types.\n *\n * @param key - Environment variable name(s) to load\n * @param options - `{ required: true }`\n * @public\n * @example\n * ```ts\n * class Config extends Envapter {\n *   \\@Envapt('API_KEY', { required: true })\n *   declare static readonly apiKey: string;\n * }\n * ```\n */\nexport function Envapt(key: EnvKeyInput, options: { required: true }): PropertyDecorator;\n\n/**\n * Classic API: No fallback\n *\n * @param key - Environment variable name(s) to load\n * @public\n * @example\n * ```ts\n * // Classic API: no fallback — property will resolve from env or be null\n * class Config extends Envapter {\n *   \\@Envapt('SIMPLE_VALUE')\n *   static readonly simple?: string | null;\n * }\n * ```\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport function Envapt<_TReturnType = string | null>(key: EnvKeyInput): PropertyDecorator;\n\n/**\n * Classic API: Primitive fallback only\n *\n * @param key - Environment variable name(s) to load\n * @param fallback - Default primitive value\n * @param converter - Optional primitive constructor (String, Number, etc.)\n * @public\n * @deprecated - Use the options object: `@Envapt('KEY', { converter, fallback })`. The positional\n * form only accepts primitive constructors and cannot express built-in tokens, array/custom\n * converters, `schema`, or `required`. Deprecated in v5, removed in v6.\n * @example\n * ```ts\n * // Classic API with primitive fallback and optional primitive converter\n * class Config extends Envapter {\n *   // Provide fallback only\n *   \\@Envapt('HOST', 'localhost')\n *   static readonly host: string;\n *\n *   // Provide fallback and converter\n *   \\@Envapt('PORT', 8080, Number)\n *   static readonly port: number;\n * }\n * ```\n */\nexport function Envapt<TFallback extends string | number | boolean | bigint | symbol | undefined>(\n    key: EnvKeyInput,\n    fallback: InferPrimitiveFallbackType<TFallback>,\n    converter?: PrimitiveConstructor\n): PropertyDecorator;\n\n/**\n * Usage 6: Standard Schema v1 adapter (zod, valibot, arktype, hand-rolled). Synchronous\n * schemas only; a Promise-returning `validate` triggers a runtime\n * `InvalidUserDefinedConfig` throw. Combining `schema` with `converter` fails to match any\n * overload at compile time; the runtime Validator catches dynamic objects that bypass the\n * types.\n * @public\n */\nexport function Envapt<Schema extends StandardSchemaV1>(\n    key: EnvKeyInput,\n    options:\n        | { schema: SchemaConstraint<Schema>; fallback?: InferSchemaOutput<Schema>; required?: false }\n        | { schema: SchemaConstraint<Schema>; required: true }\n): PropertyDecorator;\n\n/**\n * Instance/Static Property decorator that automatically loads and converts environment variables.\n */\nexport function Envapt<TFallback = unknown>(\n    key: EnvKeyInput,\n    fallbackOrOptions?: TFallback | EnvaptOptions<TFallback>,\n    converter?: EnvaptConverter<TFallback>\n): PropertyDecorator {\n    // Determine if using new options API or classic API\n    let fallback: TFallback | undefined;\n    let actualConverter: EnvaptConverter<TFallback> | undefined;\n    let actualSchema: StandardSchemaV1 | undefined;\n    let hasFallback = true;\n    let required = false;\n\n    if (\n        fallbackOrOptions &&\n        typeof fallbackOrOptions === 'object' &&\n        ('fallback' in fallbackOrOptions ||\n            'converter' in fallbackOrOptions ||\n            'required' in fallbackOrOptions ||\n            'schema' in fallbackOrOptions)\n    ) {\n        const options = fallbackOrOptions as {\n            fallback?: TFallback;\n            converter?: EnvaptConverter<TFallback>;\n            required?: boolean;\n            schema?: unknown;\n        };\n        fallback = options.fallback;\n        actualConverter = options.converter;\n        hasFallback = 'fallback' in options;\n        required = options.required === true;\n\n        if (required && hasFallback && fallback !== undefined) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidUserDefinedConfig,\n                '`required: true` and `fallback` are mutually exclusive on @Envapt options. Drop the fallback or call `Envapter.require()` separately.'\n            );\n        }\n\n        if ('schema' in options && options.schema !== undefined) {\n            if (!Validator.isStandardSchema(options.schema)) {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.InvalidUserDefinedConfig,\n                    '`schema` must be a Standard Schema v1 object (zod, valibot, arktype, or any `~standard`-conformant value).'\n                );\n            }\n            if (actualConverter !== undefined) {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.InvalidUserDefinedConfig,\n                    '`schema` and `converter` are mutually exclusive on @Envapt options. Drop one as they both turn a raw env string into a typed value.'\n                );\n            }\n            actualSchema = options.schema;\n        }\n    } else {\n        // Classic API\n        fallback = fallbackOrOptions as TFallback;\n        actualConverter = converter;\n        hasFallback = arguments.length > 1;\n    }\n\n    return createPropertyDecorator(key, {\n        fallback,\n        converter: actualConverter,\n        hasFallback,\n        required,\n        schema: actualSchema\n    });\n}\n"],"mappings":"iKAwPA,SAAgB,EACZ,EACA,EACA,EACiB,CAEjB,IAAI,EACA,EACA,EACA,EAAc,GACd,EAAW,GAEf,GACI,GACA,OAAO,GAAsB,WAC5B,aAAc,GACX,cAAe,GACf,aAAc,GACd,WAAY,GAClB,CACE,IAAM,EAAU,EAWhB,GALA,EAAW,EAAQ,SACnB,EAAkB,EAAQ,UAC1B,EAAc,aAAc,EAC5B,EAAW,EAAQ,WAAa,GAE5B,GAAY,GAAe,IAAa,IAAA,GACxC,MAAM,IAAI,EAAA,IAEN,uIACJ,EAGJ,GAAI,WAAY,GAAW,EAAQ,SAAW,IAAA,GAAW,CACrD,GAAI,CAAC,EAAU,iBAAiB,EAAQ,MAAM,EAC1C,MAAM,IAAI,EAAA,IAEN,4GACJ,EAEJ,GAAI,IAAoB,IAAA,GACpB,MAAM,IAAI,EAAA,IAEN,qIACJ,EAEJ,EAAe,EAAQ,MAC3B,CACJ,MAEI,EAAW,EACX,EAAkB,EAClB,EAAc,UAAU,OAAS,EAGrC,OAAO,EAAwB,EAAK,CAChC,WACA,UAAW,EACX,cACA,WACA,OAAQ,CACZ,CAAC,CACL"}
+{"version":3,"file":"Envapt.mjs","names":[],"sources":["../../../src/decorators/Envapt.ts"],"sourcesContent":["import { createPropertyDecorator } from './createPropertyDecorator';\nimport { EnvaptError, EnvaptErrorCodes } from '../Error';\nimport { Validator } from '../Validators';\n\nimport type { ArrayOf } from '../converters';\nimport type { InferSchemaOutput, StandardSchemaV1 } from '../StandardSchema';\nimport type {\n    BuiltInConverter,\n    ConverterFunction,\n    EnvKeyInput,\n    EnvaptConverter,\n    InferConverterFallbackType,\n    InferPrimitiveReturnType,\n    PrimitiveConstructor,\n    SchemaConstraint\n} from '../types';\n\n/**\n * Usage 1: Either a custom converter function + fallback (both required), OR a fallback\n * only (no converter).\n *\n * @param key - Environment variable name(s) to load\n * @param options - Configuration options\n * @public\n * @example\n * ```ts\n * class Config extends Envapter {\n *   // Custom converter that validates a non-empty API key\n *   \\@Envapt('API_KEY', {\n *     fallback: 'default-key',\n *     converter(raw, _fallback) {\n *       if (!raw || raw.trim() === '') throw new Error('API_KEY required');\n *       return raw.trim();\n *     }\n *   })\n *   static readonly apiKey: string;\n *\n *   // Fallback-only (no converter): string fallback\n *   \\@Envapt('LOG_FILE', { fallback: '/var/log/app.log' })\n *   static readonly logFile: string;\n *\n *   // Fallback-only: arbitrary object fallback\n *   \\@Envapt('RETRY_POLICY', { fallback: { retries: 3, backoff: 'exponential' } })\n *   static readonly retryPolicy: unknown;\n * }\n * ```\n */\nexport function Envapt<TFallback>(\n    key: EnvKeyInput,\n    options:\n        | { converter: (raw: string | undefined, fallback: TFallback) => TFallback; fallback: TFallback }\n        | { fallback: TFallback; converter?: undefined }\n): PropertyDecorator;\n\n/**\n * Usage 2: Custom converter function without fallback. Either omit `required` (returns the\n * converter's output, possibly `undefined`) or pass `required: true` to throw `MissingEnvValue`\n * on missing/empty values.\n *\n * @param key - Environment variable name(s) to load\n * @param options - Configuration options with custom converter only, with optional `required: true`\n * @public\n * @example\n * ```ts\n * class Config extends Envapter {\n *   \\@Envapt('FEATURE_FLAGS', { converter(raw) {\n *     return raw ? raw.split('|').map(s => s.trim()) : [];\n *   } })\n *   static readonly featureFlags: string[];\n *\n *   \\@Envapt('JWT_SECRET', {\n *     converter: (raw) => Buffer.from(raw ?? '', 'base64'),\n *     required: true\n *   })\n *   declare static readonly jwtSecret: Buffer;\n * }\n * ```\n */\nexport function Envapt<TReturnType>(\n    key: EnvKeyInput,\n    options:\n        | { converter: ConverterFunction<TReturnType>; required?: false }\n        | { converter: ConverterFunction<TReturnType>; required: true }\n): PropertyDecorator;\n\n/**\n * Usage 3: Built-in or array converter with optional fallback OR `required: true`.\n *\n * `InferConverterFallbackType` handles asymmetric cases: scalar `Converters.Time` accepts\n * `TimeFallback`, and `ArrayOf<'time'>` accepts `TimeFallback[]`. Every other converter\n * reduces to `InferConverterReturnType`. The two object-shape branches are mutually\n * exclusive: either provide a `fallback`, or pass `required: true` to throw\n * `MissingEnvValue` on missing/empty values.\n *\n * @param key - Environment variable name(s) to load\n * @param options - Configuration options\n * @public\n * @example\n * ```ts\n * import { Converters } from 'envapt';\n *\n * class Config extends Envapter {\n *   // Use built-in Number converter with a numeric fallback\n *   \\@Envapt('APP_PORT', { converter: Converters.Number, fallback: 3000 })\n *   static readonly port: number;\n *\n *   // Url converter: the fallback is a URL instance, not a string\n *   \\@Envapt('APP_URL', { converter: Converters.Url, fallback: new URL('http://localhost:3000') })\n *   static readonly url: URL;\n *\n *   // Prefer CANARY_URL when present, otherwise fall back to APP_URL\n *   \\@Envapt(['CANARY_URL', 'APP_URL'], { converter: Converters.Url })\n *   static readonly canaryUrl: URL | null;\n *\n *   // `Converters.Time` accepts either a number (milliseconds) or a time-string fallback (`<number><unit>`).\n *   \\@Envapt('REQUEST_TIMEOUT', { converter: Converters.Time, fallback: '10s' })\n *   static readonly requestTimeout: number;\n *\n *   // Array converter: comma-separated list of origins -> string[]\n *   \\@Envapt('ALLOWED_ORIGINS', {\n *     converter: Converters.array({ of: Converters.String }),\n *     fallback: ['https://example.com']\n *   })\n *   static readonly allowedOrigins: string[];\n *\n *   \\@Envapt('DATABASE_URL', { converter: Converters.Url, required: true })\n *   declare static readonly databaseUrl: URL;\n * }\n * ```\n */\nexport function Envapt<TConverter extends BuiltInConverter | ArrayOf>(\n    key: EnvKeyInput,\n    options:\n        | { converter: TConverter; fallback?: InferConverterFallbackType<TConverter> | undefined; required?: false }\n        | { converter: TConverter; required: true }\n): PropertyDecorator;\n\n/**\n * Usage 4: Primitive constructor with optional fallback\n *\n * @param key - Environment variable name(s) to load\n * @param options - Configuration options with primitive constructor\n * @public\n * @example\n * ```ts\n * // Use primitive constructors to coerce values\n * class Config extends Envapter {\n *   \\@Envapt('MAX_CONNECTIONS', { converter: Number, fallback: 100 })\n *   static readonly maxConnections: number;\n *\n *   \\@Envapt('FEATURE_ENABLED', { converter: Boolean, fallback: false })\n *   static readonly featureEnabled: boolean;\n * }\n * ```\n */\nexport function Envapt<TConstructor extends PrimitiveConstructor>(\n    key: EnvKeyInput,\n    options:\n        | { converter: TConstructor; fallback?: InferPrimitiveReturnType<TConstructor>; required?: false }\n        | { converter: TConstructor; required: true }\n): PropertyDecorator;\n\n/**\n * Usage 5: Required, no converter (raw string). Throws `MissingEnvValue` on first access if\n * the env value is missing or empty (post-trim). Independent of global `Envapter.strict`.\n * Combining `required: true` with `fallback` fails to match any overload at compile time;\n * the runtime Validator catches dynamic objects that bypass the types.\n *\n * @param key - Environment variable name(s) to load\n * @param options - `{ required: true }`\n * @public\n * @example\n * ```ts\n * class Config extends Envapter {\n *   \\@Envapt('API_KEY', { required: true })\n *   declare static readonly apiKey: string;\n * }\n * ```\n */\nexport function Envapt(key: EnvKeyInput, options: { required: true }): PropertyDecorator;\n\n/**\n * No-fallback form. The property resolves from env or `null`.\n *\n * @param key - Environment variable name(s) to load\n * @public\n * @example\n * ```ts\n * // Classic API: no fallback — property will resolve from env or be null\n * class Config extends Envapter {\n *   \\@Envapt('SIMPLE_VALUE')\n *   static readonly simple?: string | null;\n * }\n * ```\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport function Envapt<_TReturnType = string | null>(key: EnvKeyInput): PropertyDecorator;\n\n/**\n * Usage 6: Standard Schema v1 adapter (zod, valibot, arktype, hand-rolled). Synchronous\n * schemas only; a Promise-returning `validate` triggers a runtime\n * `InvalidUserDefinedConfig` throw. Combining `schema` with `converter` fails to match any\n * overload at compile time; the runtime Validator catches dynamic objects that bypass the\n * types.\n * @public\n */\nexport function Envapt<Schema extends StandardSchemaV1>(\n    key: EnvKeyInput,\n    options:\n        | { schema: SchemaConstraint<Schema>; fallback?: InferSchemaOutput<Schema>; required?: false }\n        | { schema: SchemaConstraint<Schema>; required: true }\n): PropertyDecorator;\n\n/**\n * Instance/Static Property decorator that automatically loads and converts environment variables.\n */\nexport function Envapt<TFallback = unknown>(key: EnvKeyInput, options?: unknown): PropertyDecorator {\n    let fallback: TFallback | undefined;\n    let actualConverter: EnvaptConverter<TFallback> | undefined;\n    let actualSchema: StandardSchemaV1 | undefined;\n    let hasFallback = false;\n    let required = false;\n\n    if (options !== undefined) {\n        if (\n            typeof options !== 'object' ||\n            options === null ||\n            !('fallback' in options || 'converter' in options || 'required' in options || 'schema' in options)\n        ) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidUserDefinedConfig,\n                'The positional `@Envapt(key, fallback, converter)` form was removed in v6. Pass an options object instead, like `@Envapt(key, { converter, fallback })`, or use one of the sugar decorators.'\n            );\n        }\n\n        const opts = options as {\n            fallback?: TFallback;\n            converter?: EnvaptConverter<TFallback>;\n            required?: boolean;\n            schema?: unknown;\n        };\n        fallback = opts.fallback;\n        actualConverter = opts.converter;\n        hasFallback = 'fallback' in opts;\n        required = opts.required === true;\n\n        if (required && hasFallback && fallback !== undefined) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidUserDefinedConfig,\n                '`required: true` and `fallback` are mutually exclusive on @Envapt options. Drop the fallback or call `Envapter.require()` separately.'\n            );\n        }\n\n        if ('schema' in opts && opts.schema !== undefined) {\n            if (!Validator.isStandardSchema(opts.schema)) {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.InvalidUserDefinedConfig,\n                    '`schema` must be a Standard Schema v1 object (zod, valibot, arktype, or any `~standard`-conformant value).'\n                );\n            }\n            if (actualConverter !== undefined) {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.InvalidUserDefinedConfig,\n                    '`schema` and `converter` are mutually exclusive on @Envapt options. Drop one as they both turn a raw env string into a typed value.'\n                );\n            }\n            actualSchema = opts.schema;\n        }\n    }\n\n    return createPropertyDecorator(key, {\n        fallback,\n        converter: actualConverter,\n        hasFallback,\n        required,\n        schema: actualSchema\n    });\n}\n"],"mappings":"iKAwNA,SAAgB,EAA4B,EAAkB,EAAsC,CAChG,IAAI,EACA,EACA,EACA,EAAc,GACd,EAAW,GAEf,GAAI,IAAY,IAAA,GAAW,CACvB,GACI,OAAO,GAAY,WACnB,GACA,EAAE,aAAc,GAAW,cAAe,GAAW,aAAc,GAAW,WAAY,GAE1F,MAAM,IAAI,EAAA,IAEN,8LACJ,EAGJ,IAAM,EAAO,EAWb,GALA,EAAW,EAAK,SAChB,EAAkB,EAAK,UACvB,EAAc,aAAc,EAC5B,EAAW,EAAK,WAAa,GAEzB,GAAY,GAAe,IAAa,IAAA,GACxC,MAAM,IAAI,EAAA,IAEN,uIACJ,EAGJ,GAAI,WAAY,GAAQ,EAAK,SAAW,IAAA,GAAW,CAC/C,GAAI,CAAC,EAAU,iBAAiB,EAAK,MAAM,EACvC,MAAM,IAAI,EAAA,IAEN,4GACJ,EAEJ,GAAI,IAAoB,IAAA,GACpB,MAAM,IAAI,EAAA,IAEN,qIACJ,EAEJ,EAAe,EAAK,MACxB,CACJ,CAEA,OAAO,EAAwB,EAAK,CAChC,WACA,UAAW,EACX,cACA,WACA,OAAQ,CACZ,CAAC,CACL"}

package/dist/workerd/index.d.mts

@@ -1,7 +1,7 @@
 import { DebugLevel } from "./Debug.mjs";
 import { EnvFileOptions } from "./Dotenv.mjs";
 import { ArrayElement, ArrayOf, ConverterToken, Converters, CustomElementConverter, isArrayOf } from "./converters/Converters.mjs";
-import { AdvancedConverterReturn, BuiltInConverter, BuiltInConverterFunction, ConditionalReturn, ConverterFunction, EnvaptConverter, InferConverterFallbackType, InferConverterReturnType, InferPrimitiveFallbackType, InferPrimitiveReturnType, JsonValue, MapOfConverterFunctions, PrimitiveConstructor, TimeFallback, TimeUnit } from "./types/Conversion.mjs";
+import { AdvancedConverterReturn, BuiltInConverter, BuiltInConverterFunction, ConditionalReturn, ConverterFunction, EnvaptConverter, InferConverterFallbackType, InferConverterReturnType, InferPrimitiveReturnType, JsonValue, MapOfConverterFunctions, PrimitiveConstructor, TimeFallback, TimeUnit } from "./types/Conversion.mjs";
 import { InferSchemaInput, InferSchemaOutput, StandardSchemaV1 } from "./StandardSchema.mjs";
 import { Err, SchemaConstraint, SchemaMustBeSync } from "./types/Schema.mjs";
 import { Environment } from "./core/EnvironmentMethods.mjs";
@@ -14,4 +14,4 @@ import { EnvBool, EnvNum, EnvStr, EnvTime, EnvUrl } from "./decorators/SugarDeco
 import { ManualEnvSource } from "./sources/ManualEnvSource.mjs";
 import { WorkerEnvSource } from "./sources/WorkerEnvSource.mjs";
 import { EnvaptError, EnvaptErrorCodes } from "./Error.mjs";
-export { type AdvancedConverterReturn, type ArrayElement, type ArrayOf, type BareEnvSource, type BuiltInConverter, type BuiltInConverterFunction, type ConditionalReturn, type ConverterFunction, type ConverterToken, Converters, type CustomElementConverter, type DebugLevel, EnvBool, type EnvFileOptions, type EnvKeyInput, EnvNum, type EnvProfile, type EnvSource, EnvStr, EnvTime, EnvUrl, Envapt, type EnvaptConverter, EnvaptError, EnvaptErrorCodes, type EnvaptOptions, Envapter, Environment, type Err, type FileEnvSource, type InferConverterFallbackType, type InferConverterReturnType, type InferPrimitiveFallbackType, type InferPrimitiveReturnType, type InferSchemaInput, type InferSchemaOutput, type JsonValue, ManualEnvSource, type MapOfConverterFunctions, type PrimitiveConstructor, type ProfilesConfig, type SchemaConstraint, type SchemaMustBeSync, type StandardSchemaV1, type TimeFallback, type TimeUnit, WorkerEnvSource, isArrayOf };
+export { type AdvancedConverterReturn, type ArrayElement, type ArrayOf, type BareEnvSource, type BuiltInConverter, type BuiltInConverterFunction, type ConditionalReturn, type ConverterFunction, type ConverterToken, Converters, type CustomElementConverter, type DebugLevel, EnvBool, type EnvFileOptions, type EnvKeyInput, EnvNum, type EnvProfile, type EnvSource, EnvStr, EnvTime, EnvUrl, Envapt, type EnvaptConverter, EnvaptError, EnvaptErrorCodes, type EnvaptOptions, Envapter, Environment, type Err, type FileEnvSource, type InferConverterFallbackType, type InferConverterReturnType, type InferPrimitiveReturnType, type InferSchemaInput, type InferSchemaOutput, type JsonValue, ManualEnvSource, type MapOfConverterFunctions, type PrimitiveConstructor, type ProfilesConfig, type SchemaConstraint, type SchemaMustBeSync, type StandardSchemaV1, type TimeFallback, type TimeUnit, WorkerEnvSource, isArrayOf };

package/dist/workerd/types/Conversion.d.mts

@@ -118,11 +118,6 @@ type AdvancedConverterReturn<TConverter, TFallback = undefined> = ConditionalRet
  * @internal
  */
 type InferPrimitiveReturnType<TConstructor extends PrimitiveConstructor> = TConstructor extends typeof String ? string : TConstructor extends typeof Number ? number : TConstructor extends typeof Boolean ? boolean : TConstructor extends typeof BigInt ? bigint : TConstructor extends typeof Symbol ? symbol : never;
-/**
- * Type inference for primitive fallback values
- * @internal
- */
-type InferPrimitiveFallbackType<TFallback extends string | number | boolean | bigint | symbol | undefined> = TFallback extends string ? string : TFallback extends number ? number : TFallback extends boolean ? boolean : TFallback extends bigint ? bigint : TFallback extends symbol ? symbol : undefined;
 //#endregion
-export type { AdvancedConverterReturn, BuiltInConverter, BuiltInConverterFunction, ConditionalReturn, ConverterFunction, EnvaptConverter, InferConverterFallbackType, InferConverterReturnType, InferPrimitiveFallbackType, InferPrimitiveReturnType, JsonValue, MapOfConverterFunctions, PrimitiveConstructor, TimeFallback, TimeUnit };
+export type { AdvancedConverterReturn, BuiltInConverter, BuiltInConverterFunction, ConditionalReturn, ConverterFunction, EnvaptConverter, InferConverterFallbackType, InferConverterReturnType, InferPrimitiveReturnType, JsonValue, MapOfConverterFunctions, PrimitiveConstructor, TimeFallback, TimeUnit };
 //# sourceMappingURL=Conversion.d.mts.map

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "envapt",
   "type": "module",
-  "version": "5.2.0",
-  "description": "Type-safe environment variables for TypeScript. Zero-dependency .env loader and parser with one API across Node, Bun, Deno, Cloudflare Workers, and the Browser. Decorators, converters, Standard Schema (zod/valibot/arktype) validation, and much more.",
+  "version": "6.0.1",
+  "description": "Type-safe config for TypeScript. Read typed values from any source, process.env, .env files, Cloudflare Workers bindings, browser bundles, or any object you supply. Zero runtime dependencies, one API across Node, Bun, Deno, Workers, and the browser. Decorators, converters, and Standard Schema (zod/valibot/arktype) validation.",
   "types": "./dist/node/index.d.mts",
   "exports": {
     ".": {
@@ -111,11 +111,11 @@
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "0.16.14",
-    "@cloudflare/workers-types": "^4.20260609.1",
+    "@cloudflare/workers-types": "^4.20260613.1",
     "@vitest/browser": "4.1.7",
     "@vitest/browser-playwright": "4.1.7",
     "arktype": "^2.2.0",
-    "esbuild": "^0.28.0",
+    "esbuild": "^0.28.1",
     "playwright": "1.60.0",
     "valibot": "^1.4.1",
     "zod": "4.4.3"
@@ -146,5 +146,5 @@
     "bump": "pnpm tsx ../../scripts/bump-jsr.ts",
     "release": "pnpm run cs:publish"
   },
-  "readme": "<img src=\"https://raw.githubusercontent.com/materwelonDhruv/envapt/main/.github/assets/logo.png\" width=\"120\" align=\"left\" alt=\"envapt logo\" />\n\n<h3>envapt</h3>\n\n<p>\n  <strong>The apt way to handle environment variables.</strong><br/>\n  Read them as typed values, with zero runtime dependencies.\n</p>\n\n<p>\n  <a href=\"https://www.npmjs.com/package/envapt\"><img alt=\"npm\" src=\"https://img.shields.io/npm/v/envapt?logo=npm&logoColor=cb3838&label=%20&labelColor=103544&color=cb3838\"></a>\n  <a href=\"https://www.npmjs.com/package/envapt\"><img alt=\"downloads\" src=\"https://img.shields.io/npm/dm/envapt?style=flat&color=f7f6e8&labelColor=103544&label=downloads\"></a>\n  <a href=\"https://jsr.io/@materwelon/envapt\"><img alt=\"jsr\" src=\"https://jsr.io/badges/@materwelon/envapt\"></a>\n  <img alt=\"CI\" src=\"https://img.shields.io/github/actions/workflow/status/materwelonDhruv/envapt/checks.yml?branch=main&label=tests&style=flat&logo=github&color=3fb950&labelColor=103544\">\n  <a href=\"LICENSE\"><img alt=\"License\" src=\"https://img.shields.io/npm/l/envapt?style=flat&color=e97826&logo=apache&label=\"></a>\n</p>\n\n<br clear=\"left\"/>\n\n`process.env` always hands you a `string | undefined`. envapt returns the type you asked for, with a\nfallback that removes `undefined` from the return type. On Node, Bun, and Deno it reads `process.env`\nand your `.env` files; on Cloudflare Workers and in the browser you bind the source with\n`Envapter.useSource(...)`.\n\n```ts\nimport { Envapter } from 'envapt';\n\nconst port = Envapter.getNumber('PORT', 3000); // number, not string | undefined\n```\n\n**[Read the docs →](https://envapt.materwelon.dev)**\n\n## What you get\n\n- **Typed values.** A fallback removes `undefined` from the return type. Built-in converters cover\n  numbers, booleans, bigint, JSON, URLs, regular expressions, dates, durations, and arrays, or pass\n  your own function or a Standard Schema validator (zod, valibot, arktype).\n- **Zero runtime dependencies.** envapt ships its own `.env` parser, so nothing is added to your\n  dependency tree.\n- **Runs on Node, Bun, Deno, Cloudflare Workers, and the browser.** Node `>=20`, Bun `>=1.3`, Deno\n  `>=2.5` (ESM and CJS); the Workers and browser builds resolve through the package `exports`\n  conditions.\n- **`.env` loading on Node, Bun, and Deno.** A per-environment file cascade, `${VAR}` templates, and\n  strict / required checks. Off Node there is no filesystem, so you bind a source with\n  `Envapter.useSource(...)` and read with the same typed API.\n\n## Install\n\n```sh\nnpm install envapt\npnpm add envapt\nyarn add envapt\nbun add envapt\ndeno add jsr:@materwelon/envapt\n```\n\n## Quick start\n\nRead values functionally with `Envapter`, or bind them to class fields with the `@Envapt` decorator.\nBoth share the same parsing, converters, and cache.\n\n### Functional\n\nRead a value from any call site, in JavaScript or TypeScript. No build step. On Node the source is\nbound for you; on Workers and in the browser, call `Envapter.useSource(...)` first.\n\n```ts\nimport { Envapter, Converters } from 'envapt';\n\nconst port = Envapter.getNumber('PORT', 3000);\nconst origins = Envapter.getUsing('ALLOWED_ORIGINS', Converters.array(), []);\n```\n\nOn Cloudflare Workers, `env` is importable at module scope, so bind it once in a config module; in the\nbrowser, seed a `ManualEnvSource` from the object your bundler injects.\n\n```ts\nimport { env } from 'cloudflare:workers';\nimport { Envapter, WorkerEnvSource } from 'envapt';\n\nEnvapter.useSource(new WorkerEnvSource(env));\n\nexport const apiToken = Envapter.get('API_TOKEN');\n```\n\n### Decorator\n\nBind a value to a class field. TypeScript, with `experimentalDecorators` in your `tsconfig.json`.\n\n```ts\nimport { Envapt, Converters } from 'envapt';\n\nclass Config {\n    @Envapt('PORT', { converter: Converters.Number, fallback: 3000 })\n    declare static readonly port: number;\n}\n```\n\n## Documentation\n\nThe guide, converter reference, validation, configuration, and the v4 to v5 migration live at\n**[envapt.materwelon.dev](https://envapt.materwelon.dev)**.\n\n## Agent skill\n\nInstall the envapt agent skill so AI coding tools use the correct API:\n\n```sh\nnpx skills add materwelonDhruv/envapt\n```\n\n---\n\n<p align=\"center\"><sub>Built by <a href=\"https://github.com/materwelondhruv\">@materwelonDhruv</a> · Apache 2.0</sub></p>\n"
+  "readme": "<img src=\"https://raw.githubusercontent.com/materwelonDhruv/envapt/main/.github/assets/logo.png\" width=\"120\" align=\"left\" alt=\"envapt logo\" />\n\n<h3>envapt</h3>\n\n<p>\n  <strong>The apt way to read typed config.</strong><br/>\n  Read config from any source as real typed values, with zero runtime dependencies.\n</p>\n\n<p>\n  <a href=\"https://www.npmjs.com/package/envapt\"><img alt=\"npm\" src=\"https://img.shields.io/npm/v/envapt?logo=npm&logoColor=cb3838&label=%20&labelColor=103544&color=cb3838\"></a>\n  <a href=\"https://www.npmjs.com/package/envapt\"><img alt=\"downloads\" src=\"https://img.shields.io/npm/dm/envapt?style=flat&color=f7f6e8&labelColor=103544&label=downloads\"></a>\n  <a href=\"https://jsr.io/@materwelon/envapt\"><img alt=\"jsr\" src=\"https://jsr.io/badges/@materwelon/envapt\"></a>\n  <img alt=\"CI\" src=\"https://img.shields.io/github/actions/workflow/status/materwelonDhruv/envapt/checks.yml?branch=main&label=tests&style=flat&logo=github&color=3fb950&labelColor=103544\">\n  <a href=\"LICENSE\"><img alt=\"License\" src=\"https://img.shields.io/npm/l/envapt?style=flat&color=e97826&logo=apache&label=\"></a>\n</p>\n\n<br clear=\"left\"/>\n\nenvapt returns config as the type you asked for instead of the `string | undefined` you get raw, with\na fallback that removes `undefined` from the return type. It reads from whatever source you bind. On\nNode, Bun, and Deno that is `process.env` and your `.env` files, bound on import. On Cloudflare\nWorkers, in the browser, or for a secrets object you fetched at boot, you bind the source with\n`Envapter.useSource(...)`.\n\n```ts\nimport { Envapter } from 'envapt';\n\nconst port = Envapter.getNumber('PORT', 3000); // number, not string | undefined\n```\n\n**[Read the docs →](https://envapt.materwelon.dev)**\n\n## What you get\n\n- **Typed values.** A fallback removes `undefined` from the return type. Built-in converters cover\n  numbers, booleans, bigint, JSON, URLs, regular expressions, dates, durations, and arrays, or pass\n  your own function or a Standard Schema validator (zod, valibot, arktype).\n- **Any source.** A source is any object with a `readVars()` method, so you can bind `process.env`, a\n  Cloudflare Workers binding, a browser bundle, or a secrets payload you fetched from a store at boot.\n  On Node, Bun, and Deno one binds on import.\n- **Zero runtime dependencies.** The reader, converters, and built-in `.env` parser are self-contained,\n  so nothing is added to your dependency tree.\n- **Runs on Node, Bun, Deno, Cloudflare Workers, and the browser.** Node `>=20`, Bun `>=1.3`, Deno\n  `>=2.5` (ESM and CJS). The Workers and browser builds resolve through the package `exports`\n  conditions.\n- **`.env` loading built in on Node.** The default Node source adds a per-environment file cascade,\n  `${VAR}` templates, and strict / required checks. Off Node there is no filesystem, so you bind\n  another source with `Envapter.useSource(...)` and read with the same typed API.\n\n## Install\n\n```sh\nnpm install envapt\npnpm add envapt\nyarn add envapt\nbun add envapt\ndeno add jsr:@materwelon/envapt\n```\n\n## Quick start\n\nRead values functionally with `Envapter`, or bind them to class fields with the `@Envapt` decorator.\nBoth share the same parsing, converters, and cache.\n\n### Functional\n\nRead a value from any call site, in JavaScript or TypeScript. No build step. On Node the source is\nbound for you. On Workers and in the browser, call `Envapter.useSource(...)` first.\n\n```ts\nimport { Envapter, Converters } from 'envapt';\n\nconst port = Envapter.getNumber('PORT', 3000);\nconst origins = Envapter.getUsing('ALLOWED_ORIGINS', Converters.array(), []);\n```\n\nOn Cloudflare Workers, `env` is importable at module scope, so bind it once in a config module; in the\nbrowser, seed a `ManualEnvSource` from the object your bundler injects.\n\n```ts\nimport { env } from 'cloudflare:workers';\nimport { Envapter, WorkerEnvSource } from 'envapt';\n\nEnvapter.useSource(new WorkerEnvSource(env));\n\nexport const apiToken = Envapter.get('API_TOKEN');\n```\n\n### Decorator\n\nBind a value to a class field. TypeScript, with `experimentalDecorators` in your `tsconfig.json`.\n\n```ts\nimport { Envapt, Converters } from 'envapt';\n\nclass Config {\n    @Envapt('PORT', { converter: Converters.Number, fallback: 3000 })\n    declare static readonly port: number;\n}\n```\n\n## Documentation\n\nThe guide, converter reference, validation, configuration, and the v4 to v5 migration live at\n**[envapt.materwelon.dev](https://envapt.materwelon.dev)**.\n\n## Agent skill\n\nInstall the envapt agent skill so AI coding tools use the correct API:\n\n```sh\nnpx skills add materwelonDhruv/envapt\n```\n\n---\n\n<p align=\"center\"><sub>Built by <a href=\"https://github.com/materwelondhruv\">@materwelonDhruv</a> · Apache 2.0</sub></p>\n"
 }