envapt 8.1.1 → 8.2.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # envapt
 
+## 8.2.1
+
+### Patch Changes
+
+- ed74814: Remove unused internal re-exports.
+- 3df9da4: Updated comments.
+
+## 8.2.0
+
+### Minor Changes
+
+- Raise the bun engine floor to 1.3.11. They finally fixed the decorator bug.
+
 ## 8.1.1
 
 ### Patch Changes
@@ -70,8 +83,7 @@
 
 ### Minor Changes
 
-- Add `PortableSource` and the `Source` type, the v8 names for the no-filesystem source class and the general source type.
-  `PortableSource` replaces both `ManualEnvSource` and `WorkerEnvSource`, which are now deprecated subclasses of it, so migrate `new ManualEnvSource(obj)` and `new WorkerEnvSource(env)` to `new PortableSource(...)`. `Source` replaces the now-deprecated `EnvSource` type. `PortableSource`'s constructor accepts any `object`, so a Cloudflare `Env` binding (an interface with no index signature) can be passed directly without a cast. Every deprecated name still works and is removed or renamed in v8.
+- Add `PortableSource` and the `Source` type, the v8 names for the no-filesystem source class and the general source type. `PortableSource` replaces both `ManualEnvSource` and `WorkerEnvSource`, which are now deprecated subclasses of it, so migrate `new ManualEnvSource(obj)` and `new WorkerEnvSource(env)` to `new PortableSource(...)`. `Source` replaces the now-deprecated `EnvSource` type. `PortableSource`'s constructor accepts any `object`, so a Cloudflare `Env` binding (an interface with no index signature) can be passed directly without a cast. Every deprecated name still works and is removed or renamed in v8.
 
 ## 7.0.3
 
@@ -318,19 +330,10 @@
     No public API change.
 
 - 9711554: Instance `get` now narrows its return type on a fallback. A redundant overload made `env.get('KEY', 'fallback')` resolve to `string | undefined` instead of `string`; removing it makes instance `get` match static `get`.
-- 9711554: Minify the published build and mark the package side-effect-free except the `envapt/config` entry. The
-  `dist` output is now minified (roughly halving the npm install size), and the `sideEffects` field lets
-  bundlers tree-shake the parts of the surface a consumer does not import. No API or behavior change.
-- 9711554: Rewrite the README for v5. The package README is now a short, docs-first landing page: hero, the
-  `process.env` to typed-value pitch, install for npm/pnpm/yarn/bun/Deno (JSR), and one quick start each
-  for the functional and decorator APIs, an agent-skill install line, with the full reference linked at
-  the docs site. Removes the stale v4 surface (the old converter enum, `dotenvConfig`, Node `>=22`, "dotenv bundled").
-
-    Also refresh the npm `description` and `keywords` for registry and search discoverability (adds
-    `typescript`, `type-safe`, `deno`, `bun`, `zod`, `valibot`, `arktype`, `validation`, `decorator`,
-    `cross-runtime`, and related terms), and fix the `@Envapt` url-converter `@example` to pass a `URL`
-    instance for the fallback instead of a string (the previous example would throw at runtime, since the
-    url converter validates the fallback as `instanceof URL`).
+- 9711554: Minify the published build and mark the package side-effect-free except the `envapt/config` entry. The `dist` output is now minified (roughly halving the npm install size), and the `sideEffects` field lets bundlers tree-shake the parts of the surface a consumer does not import. No API or behavior change.
+- 9711554: Rewrite the README for v5. The package README is now a short, docs-first landing page: hero, the `process.env` to typed-value pitch, install for npm/pnpm/yarn/bun/Deno (JSR), and one quick start each for the functional and decorator APIs, an agent-skill install line, with the full reference linked at the docs site. Removes the stale v4 surface (the old converter enum, `dotenvConfig`, Node `>=22`, "dotenv bundled").
+
+    Also refresh the npm `description` and `keywords` for registry and search discoverability (adds `typescript`, `type-safe`, `deno`, `bun`, `zod`, `valibot`, `arktype`, `validation`, `decorator`, `cross-runtime`, and related terms), and fix the `@Envapt` url-converter `@example` to pass a `URL` instance for the fallback instead of a string (the previous example would throw at runtime, since the url converter validates the fallback as `instanceof URL`).
 
 ## 4.1.1
 

package/README.md

@@ -17,11 +17,10 @@
 
 <br clear="left"/>
 
-envapt returns config as the type you asked for instead of the `string | undefined` you get raw, with
-a fallback that removes `undefined` from the return type. It reads from whatever source you bind. On
-Node, Bun, and Deno that is `process.env` and your `.env` files, bound on import. On Cloudflare
-Workers, in the browser, or for a secrets object you fetched at boot, you bind the source with
-`Envapter.useSource(...)`.
+envapt returns config as the type you asked for, with a fallback that removes `undefined` from the
+return type. It reads from whatever source you bind. On Node, Bun, and Deno that is `process.env`
+and your `.env` files, bound on import. On Cloudflare Workers, in the browser, or for a secrets
+object you fetched at boot, you bind the source with `Envapter.useSource(...)`.
 
 ```ts
 import { Converters, Envapter } from 'envapt';
@@ -54,7 +53,7 @@ missing. Reads with a fallback (`Envapter.getNumber('WORKERS', 4)`) never throw.
   On Node, Bun, and Deno one binds on import.
 - **Zero runtime dependencies.** The reader, converters, and built-in `.env` parser are self-contained,
   so nothing is added to your dependency tree.
-- **Runs on Node, Bun, Deno, Cloudflare Workers, and the browser.** Node `>=20`, Bun `>=1.3`, Deno
+- **Runs on Node, Bun, Deno, Cloudflare Workers, and the browser.** Node `>=20`, Bun `>=1.3.11`, Deno
   `>=2.5` (ESM and CJS). The portable build resolves through the package `exports`
   conditions.
 - **`.env` loading built in on Node.** The default Node source adds a per-environment file cascade,

package/dist/node/config.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"config.cjs","names":["Envapter"],"sources":["../../src/config.ts"],"sourcesContent":["/**\n * Side-effect entry (`import 'envapt/config'`, `node --import envapt/config`, `-r envapt/config` for\n * CJS). A drop-in for `dotenv/config` that loads the `.env` cascade and mirrors it into `process.env`.\n *\n * Set `ENVAPT_DEBUG=verbose` before the import to log the load. Setting `Envapter.debug` in code after\n * the import is too late, the load has already run.\n *\n * @module\n */\n\nimport { Envapter } from '.';\n\n// Importing Envapter evaluates NodeEnvapter, whose static block binds the default source before load() runs.\nEnvapter.syncProcessEnv = true;\nEnvapter.load();\n"],"mappings":"6CAaA,EAAA,aAAS,eAAiB,GAC1BA,EAAAA,aAAS,KAAK"}
+{"version":3,"file":"config.cjs","names":["Envapter"],"sources":["../../src/config.ts"],"sourcesContent":["/**\n * Side-effect entry (`import 'envapt/config'`, `node --import envapt/config`, `-r envapt/config` for\n * CJS). A drop-in for `dotenv/config` that loads the `.env` cascade and mirrors it into `process.env`.\n *\n * Set `ENVAPT_DEBUG=verbose` before the import to log the load. Setting `Envapter.debug` in code after\n * the import is too late because the load has already run.\n *\n * @module\n */\n\nimport { Envapter } from '.';\n\n// Importing Envapter evaluates NodeEnvapter, whose static block binds the default source before load() runs.\nEnvapter.syncProcessEnv = true;\nEnvapter.load();\n"],"mappings":"6CAaA,EAAA,aAAS,eAAiB,GAC1BA,EAAAA,aAAS,KAAK"}

package/dist/node/config.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"config.mjs","names":["Envapter"],"sources":["../../src/config.ts"],"sourcesContent":["/**\n * Side-effect entry (`import 'envapt/config'`, `node --import envapt/config`, `-r envapt/config` for\n * CJS). A drop-in for `dotenv/config` that loads the `.env` cascade and mirrors it into `process.env`.\n *\n * Set `ENVAPT_DEBUG=verbose` before the import to log the load. Setting `Envapter.debug` in code after\n * the import is too late, the load has already run.\n *\n * @module\n */\n\nimport { Envapter } from '.';\n\n// Importing Envapter evaluates NodeEnvapter, whose static block binds the default source before load() runs.\nEnvapter.syncProcessEnv = true;\nEnvapter.load();\n"],"mappings":"yDAaA,EAAS,eAAiB,GAC1BA,EAAS,KAAK"}
+{"version":3,"file":"config.mjs","names":["Envapter"],"sources":["../../src/config.ts"],"sourcesContent":["/**\n * Side-effect entry (`import 'envapt/config'`, `node --import envapt/config`, `-r envapt/config` for\n * CJS). A drop-in for `dotenv/config` that loads the `.env` cascade and mirrors it into `process.env`.\n *\n * Set `ENVAPT_DEBUG=verbose` before the import to log the load. Setting `Envapter.debug` in code after\n * the import is too late because the load has already run.\n *\n * @module\n */\n\nimport { Envapter } from '.';\n\n// Importing Envapter evaluates NodeEnvapter, whose static block binds the default source before load() runs.\nEnvapter.syncProcessEnv = true;\nEnvapter.load();\n"],"mappings":"yDAaA,EAAS,eAAiB,GAC1BA,EAAS,KAAK"}

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

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

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"Converters.cjs","names":[],"sources":["../../../src/converters/Converters.ts"],"sourcesContent":["const SCALAR = {\n    String: 'string',\n    Number: 'number',\n    Boolean: 'boolean',\n    Bigint: 'bigint',\n    Symbol: 'symbol',\n    Integer: 'integer',\n    Float: 'float',\n    Json: 'json',\n    Url: 'url',\n    Regexp: 'regexp',\n    Date: 'date',\n    Time: 'time',\n    Port: 'port',\n    Email: 'email'\n} as const;\n\nexport type ConverterToken = (typeof SCALAR)[keyof typeof SCALAR];\n\n/**\n * Custom element converter for use inside {@link Converters.array}. Receives the trimmed,\n * non-empty raw string for one array slot and returns the parsed value.\n * @public\n * @see {@link https://envapt.materwelon.dev/docs/converters#custom-converters}\n */\nexport type CustomElementConverter<TReturn = unknown> = (raw: string) => TReturn;\n\n// json/regexp are not allowed as array elements because they consume the whole string and cannot be split into slots\nexport type ArrayElement = Exclude<ConverterToken, 'json' | 'regexp'> | CustomElementConverter;\n\n// phantom type branded with __envaptKind for runtime dispatch. TElement preserves\n// element converter type through variable indirection for type inference\nexport interface ArrayOf<TElement extends ArrayElement = ArrayElement> {\n    readonly __envaptKind: 'array';\n    readonly of: TElement;\n    readonly delimiter: string;\n}\n\nexport function isArrayOf(value: unknown): value is ArrayOf {\n    return typeof value === 'object' && value !== null && '__envaptKind' in value && value.__envaptKind === 'array';\n}\n\ntype ArrayScalarElement = Exclude<ConverterToken, 'json' | 'regexp'>;\n\nfunction buildArrayConverter<TReturn>(opts: {\n    of: CustomElementConverter<TReturn>;\n    delimiter?: string;\n}): ArrayOf<CustomElementConverter<TReturn>>;\nfunction buildArrayConverter<TToken extends ArrayScalarElement>(opts: {\n    of: TToken;\n    delimiter?: string;\n}): ArrayOf<TToken>;\nfunction buildArrayConverter(opts?: { delimiter?: string }): ArrayOf<'string'>;\nfunction buildArrayConverter(opts?: { of?: ArrayElement; delimiter?: string }): ArrayOf<ArrayElement> {\n    return {\n        __envaptKind: 'array',\n        of: opts?.of ?? SCALAR.String,\n        delimiter: opts?.delimiter ?? ','\n    };\n}\n\n/**\n * Built-in converters for environment variables. Use the scalar tokens (e.g. `Converters.Number`)\n * for primitive types and the {@link Converters.array} builder for delimited lists.\n *\n * @example\n * ```ts\n * \\@Envapt('PORT', { converter: Converters.Number, fallback: 3000 })\n * static readonly port: number;\n *\n * \\@Envapt('TAGS', { converter: Converters.array({ of: Converters.String, delimiter: ' ' }) })\n * static readonly tags: string[];\n * ```\n *\n * @public\n * @see {@link https://envapt.materwelon.dev/docs/converters#built-in-tokens}\n */\nexport const Converters = {\n    ...SCALAR,\n    array: buildArrayConverter\n} as const;\n"],"mappings":"AAAA,MAAM,EAAS,CACX,OAAQ,SACR,OAAQ,SACR,QAAS,UACT,OAAQ,SACR,OAAQ,SACR,QAAS,UACT,MAAO,QACP,KAAM,OACN,IAAK,MACL,OAAQ,SACR,KAAM,OACN,KAAM,OACN,KAAM,OACN,MAAO,OACX,EAuBA,SAAgB,EAAU,EAAkC,CACxD,OAAO,OAAO,GAAU,YAAY,GAAkB,iBAAkB,GAAS,EAAM,eAAiB,OAC5G,CAaA,SAAS,EAAoB,EAAyE,CAClG,MAAO,CACH,aAAc,QACd,GAAI,GAAM,IAAM,EAAO,OACvB,UAAW,GAAM,WAAa,GAClC,CACJ,CAkBA,MAAa,EAAa,CACtB,GAAG,EACH,MAAO,CACX"}
+{"version":3,"file":"Converters.cjs","names":[],"sources":["../../../src/converters/Converters.ts"],"sourcesContent":["const SCALAR = {\n    String: 'string',\n    Number: 'number',\n    Boolean: 'boolean',\n    Bigint: 'bigint',\n    Symbol: 'symbol',\n    Integer: 'integer',\n    Float: 'float',\n    Json: 'json',\n    Url: 'url',\n    Regexp: 'regexp',\n    Date: 'date',\n    Time: 'time',\n    Port: 'port',\n    Email: 'email'\n} as const;\n\nexport type ConverterToken = (typeof SCALAR)[keyof typeof SCALAR];\n\n/**\n * Custom element converter for use inside {@link Converters.array}. Receives the trimmed,\n * non-empty raw string for one array slot and returns the parsed value.\n * @public\n * @see {@link https://envapt.materwelon.dev/docs/converters#custom-converters}\n */\nexport type CustomElementConverter<TReturn = unknown> = (raw: string) => TReturn;\n\n// json and regexp always parse the whole string\ntype ArrayElement = Exclude<ConverterToken, 'json' | 'regexp'> | CustomElementConverter;\n\n// TElement keeps the element type when the converter is stored in a variable first\nexport interface ArrayOf<TElement extends ArrayElement = ArrayElement> {\n    readonly __envaptKind: 'array';\n    readonly of: TElement;\n    readonly delimiter: string;\n}\n\nexport function isArrayOf(value: unknown): value is ArrayOf {\n    return typeof value === 'object' && value !== null && '__envaptKind' in value && value.__envaptKind === 'array';\n}\n\ntype ArrayScalarElement = Exclude<ConverterToken, 'json' | 'regexp'>;\n\nfunction buildArrayConverter<TReturn>(opts: {\n    of: CustomElementConverter<TReturn>;\n    delimiter?: string;\n}): ArrayOf<CustomElementConverter<TReturn>>;\nfunction buildArrayConverter<TToken extends ArrayScalarElement>(opts: {\n    of: TToken;\n    delimiter?: string;\n}): ArrayOf<TToken>;\nfunction buildArrayConverter(opts?: { delimiter?: string }): ArrayOf<'string'>;\nfunction buildArrayConverter(opts?: { of?: ArrayElement; delimiter?: string }): ArrayOf<ArrayElement> {\n    return {\n        __envaptKind: 'array',\n        of: opts?.of ?? SCALAR.String,\n        delimiter: opts?.delimiter ?? ','\n    };\n}\n\n/**\n * Built-in converters for environment variables. Use the scalar tokens (e.g. `Converters.Number`)\n * for primitive types and the {@link Converters.array} builder for delimited lists.\n *\n * @example\n * ```ts\n * \\@Envapt('PORT', { converter: Converters.Number, fallback: 3000 })\n * static readonly port: number;\n *\n * \\@Envapt('TAGS', { converter: Converters.array({ of: Converters.String, delimiter: ' ' }) })\n * static readonly tags: string[];\n * ```\n *\n * @public\n * @see {@link https://envapt.materwelon.dev/docs/converters#built-in-tokens}\n */\nexport const Converters = {\n    ...SCALAR,\n    array: buildArrayConverter\n} as const;\n"],"mappings":"AAAA,MAAM,EAAS,CACX,OAAQ,SACR,OAAQ,SACR,QAAS,UACT,OAAQ,SACR,OAAQ,SACR,QAAS,UACT,MAAO,QACP,KAAM,OACN,IAAK,MACL,OAAQ,SACR,KAAM,OACN,KAAM,OACN,KAAM,OACN,MAAO,OACX,EAsBA,SAAgB,EAAU,EAAkC,CACxD,OAAO,OAAO,GAAU,YAAY,GAAkB,iBAAkB,GAAS,EAAM,eAAiB,OAC5G,CAaA,SAAS,EAAoB,EAAyE,CAClG,MAAO,CACH,aAAc,QACd,GAAI,GAAM,IAAM,EAAO,OACvB,UAAW,GAAM,WAAa,GAClC,CACJ,CAkBA,MAAa,EAAa,CACtB,GAAG,EACH,MAAO,CACX"}

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

@@ -1 +1 @@
-{"version":3,"file":"Converters.mjs","names":[],"sources":["../../../src/converters/Converters.ts"],"sourcesContent":["const SCALAR = {\n    String: 'string',\n    Number: 'number',\n    Boolean: 'boolean',\n    Bigint: 'bigint',\n    Symbol: 'symbol',\n    Integer: 'integer',\n    Float: 'float',\n    Json: 'json',\n    Url: 'url',\n    Regexp: 'regexp',\n    Date: 'date',\n    Time: 'time',\n    Port: 'port',\n    Email: 'email'\n} as const;\n\nexport type ConverterToken = (typeof SCALAR)[keyof typeof SCALAR];\n\n/**\n * Custom element converter for use inside {@link Converters.array}. Receives the trimmed,\n * non-empty raw string for one array slot and returns the parsed value.\n * @public\n * @see {@link https://envapt.materwelon.dev/docs/converters#custom-converters}\n */\nexport type CustomElementConverter<TReturn = unknown> = (raw: string) => TReturn;\n\n// json/regexp are not allowed as array elements because they consume the whole string and cannot be split into slots\nexport type ArrayElement = Exclude<ConverterToken, 'json' | 'regexp'> | CustomElementConverter;\n\n// phantom type branded with __envaptKind for runtime dispatch. TElement preserves\n// element converter type through variable indirection for type inference\nexport interface ArrayOf<TElement extends ArrayElement = ArrayElement> {\n    readonly __envaptKind: 'array';\n    readonly of: TElement;\n    readonly delimiter: string;\n}\n\nexport function isArrayOf(value: unknown): value is ArrayOf {\n    return typeof value === 'object' && value !== null && '__envaptKind' in value && value.__envaptKind === 'array';\n}\n\ntype ArrayScalarElement = Exclude<ConverterToken, 'json' | 'regexp'>;\n\nfunction buildArrayConverter<TReturn>(opts: {\n    of: CustomElementConverter<TReturn>;\n    delimiter?: string;\n}): ArrayOf<CustomElementConverter<TReturn>>;\nfunction buildArrayConverter<TToken extends ArrayScalarElement>(opts: {\n    of: TToken;\n    delimiter?: string;\n}): ArrayOf<TToken>;\nfunction buildArrayConverter(opts?: { delimiter?: string }): ArrayOf<'string'>;\nfunction buildArrayConverter(opts?: { of?: ArrayElement; delimiter?: string }): ArrayOf<ArrayElement> {\n    return {\n        __envaptKind: 'array',\n        of: opts?.of ?? SCALAR.String,\n        delimiter: opts?.delimiter ?? ','\n    };\n}\n\n/**\n * Built-in converters for environment variables. Use the scalar tokens (e.g. `Converters.Number`)\n * for primitive types and the {@link Converters.array} builder for delimited lists.\n *\n * @example\n * ```ts\n * \\@Envapt('PORT', { converter: Converters.Number, fallback: 3000 })\n * static readonly port: number;\n *\n * \\@Envapt('TAGS', { converter: Converters.array({ of: Converters.String, delimiter: ' ' }) })\n * static readonly tags: string[];\n * ```\n *\n * @public\n * @see {@link https://envapt.materwelon.dev/docs/converters#built-in-tokens}\n */\nexport const Converters = {\n    ...SCALAR,\n    array: buildArrayConverter\n} as const;\n"],"mappings":"AAAA,MAAM,EAAS,CACX,OAAQ,SACR,OAAQ,SACR,QAAS,UACT,OAAQ,SACR,OAAQ,SACR,QAAS,UACT,MAAO,QACP,KAAM,OACN,IAAK,MACL,OAAQ,SACR,KAAM,OACN,KAAM,OACN,KAAM,OACN,MAAO,OACX,EAuBA,SAAgB,EAAU,EAAkC,CACxD,OAAO,OAAO,GAAU,YAAY,GAAkB,iBAAkB,GAAS,EAAM,eAAiB,OAC5G,CAaA,SAAS,EAAoB,EAAyE,CAClG,MAAO,CACH,aAAc,QACd,GAAI,GAAM,IAAM,EAAO,OACvB,UAAW,GAAM,WAAa,GAClC,CACJ,CAkBA,MAAa,EAAa,CACtB,GAAG,EACH,MAAO,CACX"}
+{"version":3,"file":"Converters.mjs","names":[],"sources":["../../../src/converters/Converters.ts"],"sourcesContent":["const SCALAR = {\n    String: 'string',\n    Number: 'number',\n    Boolean: 'boolean',\n    Bigint: 'bigint',\n    Symbol: 'symbol',\n    Integer: 'integer',\n    Float: 'float',\n    Json: 'json',\n    Url: 'url',\n    Regexp: 'regexp',\n    Date: 'date',\n    Time: 'time',\n    Port: 'port',\n    Email: 'email'\n} as const;\n\nexport type ConverterToken = (typeof SCALAR)[keyof typeof SCALAR];\n\n/**\n * Custom element converter for use inside {@link Converters.array}. Receives the trimmed,\n * non-empty raw string for one array slot and returns the parsed value.\n * @public\n * @see {@link https://envapt.materwelon.dev/docs/converters#custom-converters}\n */\nexport type CustomElementConverter<TReturn = unknown> = (raw: string) => TReturn;\n\n// json and regexp always parse the whole string\ntype ArrayElement = Exclude<ConverterToken, 'json' | 'regexp'> | CustomElementConverter;\n\n// TElement keeps the element type when the converter is stored in a variable first\nexport interface ArrayOf<TElement extends ArrayElement = ArrayElement> {\n    readonly __envaptKind: 'array';\n    readonly of: TElement;\n    readonly delimiter: string;\n}\n\nexport function isArrayOf(value: unknown): value is ArrayOf {\n    return typeof value === 'object' && value !== null && '__envaptKind' in value && value.__envaptKind === 'array';\n}\n\ntype ArrayScalarElement = Exclude<ConverterToken, 'json' | 'regexp'>;\n\nfunction buildArrayConverter<TReturn>(opts: {\n    of: CustomElementConverter<TReturn>;\n    delimiter?: string;\n}): ArrayOf<CustomElementConverter<TReturn>>;\nfunction buildArrayConverter<TToken extends ArrayScalarElement>(opts: {\n    of: TToken;\n    delimiter?: string;\n}): ArrayOf<TToken>;\nfunction buildArrayConverter(opts?: { delimiter?: string }): ArrayOf<'string'>;\nfunction buildArrayConverter(opts?: { of?: ArrayElement; delimiter?: string }): ArrayOf<ArrayElement> {\n    return {\n        __envaptKind: 'array',\n        of: opts?.of ?? SCALAR.String,\n        delimiter: opts?.delimiter ?? ','\n    };\n}\n\n/**\n * Built-in converters for environment variables. Use the scalar tokens (e.g. `Converters.Number`)\n * for primitive types and the {@link Converters.array} builder for delimited lists.\n *\n * @example\n * ```ts\n * \\@Envapt('PORT', { converter: Converters.Number, fallback: 3000 })\n * static readonly port: number;\n *\n * \\@Envapt('TAGS', { converter: Converters.array({ of: Converters.String, delimiter: ' ' }) })\n * static readonly tags: string[];\n * ```\n *\n * @public\n * @see {@link https://envapt.materwelon.dev/docs/converters#built-in-tokens}\n */\nexport const Converters = {\n    ...SCALAR,\n    array: buildArrayConverter\n} as const;\n"],"mappings":"AAAA,MAAM,EAAS,CACX,OAAQ,SACR,OAAQ,SACR,QAAS,UACT,OAAQ,SACR,OAAQ,SACR,QAAS,UACT,MAAO,QACP,KAAM,OACN,IAAK,MACL,OAAQ,SACR,KAAM,OACN,KAAM,OACN,KAAM,OACN,MAAO,OACX,EAsBA,SAAgB,EAAU,EAAkC,CACxD,OAAO,OAAO,GAAU,YAAY,GAAkB,iBAAkB,GAAS,EAAM,eAAiB,OAC5G,CAaA,SAAS,EAAoB,EAAyE,CAClG,MAAO,CACH,aAAc,QACd,GAAI,GAAM,IAAM,EAAO,OACvB,UAAW,GAAM,WAAa,GAClC,CACJ,CAkBA,MAAa,EAAa,CACtB,GAAG,EACH,MAAO,CACX"}

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

@@ -1 +1 @@
-{"version":3,"file":"ListOfBuiltInConverters.cjs","names":["EMAIL_RE"],"sources":["../../../src/converters/ListOfBuiltInConverters.ts"],"sourcesContent":["import { EMAIL_RE, MAX_PORT } from './BuiltInConverters';\n\nimport type { ConverterToken } from './Converters';\nimport type { JsonValue } from '../types';\n\n/**\n * List of built-in scalar converters for Envapt. Arrays are handled separately via\n * the {@link Converters.array} builder and the `ArrayOf<...>` brand.\n * @internal\n */\nexport const ListOfBuiltInConverters: ConverterToken[] = [\n    'string',\n    'number',\n    'boolean',\n    'bigint',\n    'symbol',\n    'integer',\n    'float',\n    'json',\n    'url',\n    'regexp',\n    'date',\n    'time',\n    'port',\n    'email'\n] as const;\n\n/**\n * Type checking functions for built-in scalar converter return types.\n * @internal\n */\nexport const BuiltInConverterTypeCheckers: Record<ConverterToken, (value: unknown) => boolean> = {\n    string: (value: unknown): value is string => typeof value === 'string',\n    number: (value: unknown): value is number => typeof value === 'number' && !Number.isNaN(value),\n    boolean: (value: unknown): value is boolean => typeof value === 'boolean',\n    bigint: (value: unknown): value is bigint => typeof value === 'bigint',\n    symbol: (value: unknown): value is symbol => typeof value === 'symbol',\n    integer: (value: unknown): value is number => typeof value === 'number' && Number.isSafeInteger(value),\n    float: (value: unknown): value is number => typeof value === 'number' && !Number.isNaN(value),\n    json: (value: unknown): value is JsonValue => {\n        try {\n            JSON.parse(JSON.stringify(value));\n            return true;\n        } catch {\n            return false;\n        }\n    },\n    url: (value: unknown): value is URL => value instanceof URL,\n    regexp: (value: unknown): value is RegExp => value instanceof RegExp,\n    date: (value: unknown): value is Date => value instanceof Date && !Number.isNaN(value.getTime()),\n    time: (value: unknown): value is number | string => typeof value === 'number' || typeof value === 'string',\n    port: (value: unknown): value is number =>\n        typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value <= MAX_PORT,\n    email: (value: unknown): value is string => typeof value === 'string' && EMAIL_RE.test(value)\n};\n"],"mappings":"2CAUa,EAA4C,CACrD,SACA,SACA,UACA,SACA,SACA,UACA,QACA,OACA,MACA,SACA,OACA,OACA,OACA,OACJ,EAMa,EAAoF,CAC7F,OAAS,GAAoC,OAAO,GAAU,SAC9D,OAAS,GAAoC,OAAO,GAAU,UAAY,CAAC,OAAO,MAAM,CAAK,EAC7F,QAAU,GAAqC,OAAO,GAAU,UAChE,OAAS,GAAoC,OAAO,GAAU,SAC9D,OAAS,GAAoC,OAAO,GAAU,SAC9D,QAAU,GAAoC,OAAO,GAAU,UAAY,OAAO,cAAc,CAAK,EACrG,MAAQ,GAAoC,OAAO,GAAU,UAAY,CAAC,OAAO,MAAM,CAAK,EAC5F,KAAO,GAAuC,CAC1C,GAAI,CAEA,OADA,KAAK,MAAM,KAAK,UAAU,CAAK,CAAC,EACzB,EACX,MAAQ,CACJ,MAAO,EACX,CACJ,EACA,IAAM,GAAiC,aAAiB,IACxD,OAAS,GAAoC,aAAiB,OAC9D,KAAO,GAAkC,aAAiB,MAAQ,CAAC,OAAO,MAAM,EAAM,QAAQ,CAAC,EAC/F,KAAO,GAA6C,OAAO,GAAU,UAAY,OAAO,GAAU,SAClG,KAAO,GACH,OAAO,GAAU,UAAY,OAAO,cAAc,CAAK,GAAK,GAAS,GAAK,GAAA,MAC9E,MAAQ,GAAoC,OAAO,GAAU,UAAYA,EAAAA,SAAS,KAAK,CAAK,CAChG"}
+{"version":3,"file":"ListOfBuiltInConverters.cjs","names":["EMAIL_RE"],"sources":["../../../src/converters/ListOfBuiltInConverters.ts"],"sourcesContent":["import { EMAIL_RE, MAX_PORT } from './BuiltInConverters';\n\nimport type { ConverterToken } from './Converters';\nimport type { JsonValue } from '../types';\n\n// arrays go through Converters.array and are not listed here\nexport const ListOfBuiltInConverters: ConverterToken[] = [\n    'string',\n    'number',\n    'boolean',\n    'bigint',\n    'symbol',\n    'integer',\n    'float',\n    'json',\n    'url',\n    'regexp',\n    'date',\n    'time',\n    'port',\n    'email'\n] as const;\n\nexport const BuiltInConverterTypeCheckers: Record<ConverterToken, (value: unknown) => boolean> = {\n    string: (value: unknown): value is string => typeof value === 'string',\n    number: (value: unknown): value is number => typeof value === 'number' && !Number.isNaN(value),\n    boolean: (value: unknown): value is boolean => typeof value === 'boolean',\n    bigint: (value: unknown): value is bigint => typeof value === 'bigint',\n    symbol: (value: unknown): value is symbol => typeof value === 'symbol',\n    integer: (value: unknown): value is number => typeof value === 'number' && Number.isSafeInteger(value),\n    float: (value: unknown): value is number => typeof value === 'number' && !Number.isNaN(value),\n    json: (value: unknown): value is JsonValue => {\n        try {\n            JSON.parse(JSON.stringify(value));\n            return true;\n        } catch {\n            return false;\n        }\n    },\n    url: (value: unknown): value is URL => value instanceof URL,\n    regexp: (value: unknown): value is RegExp => value instanceof RegExp,\n    date: (value: unknown): value is Date => value instanceof Date && !Number.isNaN(value.getTime()),\n    time: (value: unknown): value is number | string => typeof value === 'number' || typeof value === 'string',\n    port: (value: unknown): value is number =>\n        typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value <= MAX_PORT,\n    email: (value: unknown): value is string => typeof value === 'string' && EMAIL_RE.test(value)\n};\n"],"mappings":"2CAMa,EAA4C,CACrD,SACA,SACA,UACA,SACA,SACA,UACA,QACA,OACA,MACA,SACA,OACA,OACA,OACA,OACJ,EAEa,EAAoF,CAC7F,OAAS,GAAoC,OAAO,GAAU,SAC9D,OAAS,GAAoC,OAAO,GAAU,UAAY,CAAC,OAAO,MAAM,CAAK,EAC7F,QAAU,GAAqC,OAAO,GAAU,UAChE,OAAS,GAAoC,OAAO,GAAU,SAC9D,OAAS,GAAoC,OAAO,GAAU,SAC9D,QAAU,GAAoC,OAAO,GAAU,UAAY,OAAO,cAAc,CAAK,EACrG,MAAQ,GAAoC,OAAO,GAAU,UAAY,CAAC,OAAO,MAAM,CAAK,EAC5F,KAAO,GAAuC,CAC1C,GAAI,CAEA,OADA,KAAK,MAAM,KAAK,UAAU,CAAK,CAAC,EACzB,EACX,MAAQ,CACJ,MAAO,EACX,CACJ,EACA,IAAM,GAAiC,aAAiB,IACxD,OAAS,GAAoC,aAAiB,OAC9D,KAAO,GAAkC,aAAiB,MAAQ,CAAC,OAAO,MAAM,EAAM,QAAQ,CAAC,EAC/F,KAAO,GAA6C,OAAO,GAAU,UAAY,OAAO,GAAU,SAClG,KAAO,GACH,OAAO,GAAU,UAAY,OAAO,cAAc,CAAK,GAAK,GAAS,GAAK,GAAA,MAC9E,MAAQ,GAAoC,OAAO,GAAU,UAAYA,EAAAA,SAAS,KAAK,CAAK,CAChG"}

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

@@ -1 +1 @@
-{"version":3,"file":"ListOfBuiltInConverters.mjs","names":[],"sources":["../../../src/converters/ListOfBuiltInConverters.ts"],"sourcesContent":["import { EMAIL_RE, MAX_PORT } from './BuiltInConverters';\n\nimport type { ConverterToken } from './Converters';\nimport type { JsonValue } from '../types';\n\n/**\n * List of built-in scalar converters for Envapt. Arrays are handled separately via\n * the {@link Converters.array} builder and the `ArrayOf<...>` brand.\n * @internal\n */\nexport const ListOfBuiltInConverters: ConverterToken[] = [\n    'string',\n    'number',\n    'boolean',\n    'bigint',\n    'symbol',\n    'integer',\n    'float',\n    'json',\n    'url',\n    'regexp',\n    'date',\n    'time',\n    'port',\n    'email'\n] as const;\n\n/**\n * Type checking functions for built-in scalar converter return types.\n * @internal\n */\nexport const BuiltInConverterTypeCheckers: Record<ConverterToken, (value: unknown) => boolean> = {\n    string: (value: unknown): value is string => typeof value === 'string',\n    number: (value: unknown): value is number => typeof value === 'number' && !Number.isNaN(value),\n    boolean: (value: unknown): value is boolean => typeof value === 'boolean',\n    bigint: (value: unknown): value is bigint => typeof value === 'bigint',\n    symbol: (value: unknown): value is symbol => typeof value === 'symbol',\n    integer: (value: unknown): value is number => typeof value === 'number' && Number.isSafeInteger(value),\n    float: (value: unknown): value is number => typeof value === 'number' && !Number.isNaN(value),\n    json: (value: unknown): value is JsonValue => {\n        try {\n            JSON.parse(JSON.stringify(value));\n            return true;\n        } catch {\n            return false;\n        }\n    },\n    url: (value: unknown): value is URL => value instanceof URL,\n    regexp: (value: unknown): value is RegExp => value instanceof RegExp,\n    date: (value: unknown): value is Date => value instanceof Date && !Number.isNaN(value.getTime()),\n    time: (value: unknown): value is number | string => typeof value === 'number' || typeof value === 'string',\n    port: (value: unknown): value is number =>\n        typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value <= MAX_PORT,\n    email: (value: unknown): value is string => typeof value === 'string' && EMAIL_RE.test(value)\n};\n"],"mappings":"mDAUA,MAAa,EAA4C,CACrD,SACA,SACA,UACA,SACA,SACA,UACA,QACA,OACA,MACA,SACA,OACA,OACA,OACA,OACJ,EAMa,EAAoF,CAC7F,OAAS,GAAoC,OAAO,GAAU,SAC9D,OAAS,GAAoC,OAAO,GAAU,UAAY,CAAC,OAAO,MAAM,CAAK,EAC7F,QAAU,GAAqC,OAAO,GAAU,UAChE,OAAS,GAAoC,OAAO,GAAU,SAC9D,OAAS,GAAoC,OAAO,GAAU,SAC9D,QAAU,GAAoC,OAAO,GAAU,UAAY,OAAO,cAAc,CAAK,EACrG,MAAQ,GAAoC,OAAO,GAAU,UAAY,CAAC,OAAO,MAAM,CAAK,EAC5F,KAAO,GAAuC,CAC1C,GAAI,CAEA,OADA,KAAK,MAAM,KAAK,UAAU,CAAK,CAAC,EACzB,EACX,MAAQ,CACJ,MAAO,EACX,CACJ,EACA,IAAM,GAAiC,aAAiB,IACxD,OAAS,GAAoC,aAAiB,OAC9D,KAAO,GAAkC,aAAiB,MAAQ,CAAC,OAAO,MAAM,EAAM,QAAQ,CAAC,EAC/F,KAAO,GAA6C,OAAO,GAAU,UAAY,OAAO,GAAU,SAClG,KAAO,GACH,OAAO,GAAU,UAAY,OAAO,cAAc,CAAK,GAAK,GAAS,GAAK,GAAA,MAC9E,MAAQ,GAAoC,OAAO,GAAU,UAAY,EAAS,KAAK,CAAK,CAChG"}
+{"version":3,"file":"ListOfBuiltInConverters.mjs","names":[],"sources":["../../../src/converters/ListOfBuiltInConverters.ts"],"sourcesContent":["import { EMAIL_RE, MAX_PORT } from './BuiltInConverters';\n\nimport type { ConverterToken } from './Converters';\nimport type { JsonValue } from '../types';\n\n// arrays go through Converters.array and are not listed here\nexport const ListOfBuiltInConverters: ConverterToken[] = [\n    'string',\n    'number',\n    'boolean',\n    'bigint',\n    'symbol',\n    'integer',\n    'float',\n    'json',\n    'url',\n    'regexp',\n    'date',\n    'time',\n    'port',\n    'email'\n] as const;\n\nexport const BuiltInConverterTypeCheckers: Record<ConverterToken, (value: unknown) => boolean> = {\n    string: (value: unknown): value is string => typeof value === 'string',\n    number: (value: unknown): value is number => typeof value === 'number' && !Number.isNaN(value),\n    boolean: (value: unknown): value is boolean => typeof value === 'boolean',\n    bigint: (value: unknown): value is bigint => typeof value === 'bigint',\n    symbol: (value: unknown): value is symbol => typeof value === 'symbol',\n    integer: (value: unknown): value is number => typeof value === 'number' && Number.isSafeInteger(value),\n    float: (value: unknown): value is number => typeof value === 'number' && !Number.isNaN(value),\n    json: (value: unknown): value is JsonValue => {\n        try {\n            JSON.parse(JSON.stringify(value));\n            return true;\n        } catch {\n            return false;\n        }\n    },\n    url: (value: unknown): value is URL => value instanceof URL,\n    regexp: (value: unknown): value is RegExp => value instanceof RegExp,\n    date: (value: unknown): value is Date => value instanceof Date && !Number.isNaN(value.getTime()),\n    time: (value: unknown): value is number | string => typeof value === 'number' || typeof value === 'string',\n    port: (value: unknown): value is number =>\n        typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value <= MAX_PORT,\n    email: (value: unknown): value is string => typeof value === 'string' && EMAIL_RE.test(value)\n};\n"],"mappings":"mDAMA,MAAa,EAA4C,CACrD,SACA,SACA,UACA,SACA,SACA,UACA,QACA,OACA,MACA,SACA,OACA,OACA,OACA,OACJ,EAEa,EAAoF,CAC7F,OAAS,GAAoC,OAAO,GAAU,SAC9D,OAAS,GAAoC,OAAO,GAAU,UAAY,CAAC,OAAO,MAAM,CAAK,EAC7F,QAAU,GAAqC,OAAO,GAAU,UAChE,OAAS,GAAoC,OAAO,GAAU,SAC9D,OAAS,GAAoC,OAAO,GAAU,SAC9D,QAAU,GAAoC,OAAO,GAAU,UAAY,OAAO,cAAc,CAAK,EACrG,MAAQ,GAAoC,OAAO,GAAU,UAAY,CAAC,OAAO,MAAM,CAAK,EAC5F,KAAO,GAAuC,CAC1C,GAAI,CAEA,OADA,KAAK,MAAM,KAAK,UAAU,CAAK,CAAC,EACzB,EACX,MAAQ,CACJ,MAAO,EACX,CACJ,EACA,IAAM,GAAiC,aAAiB,IACxD,OAAS,GAAoC,aAAiB,OAC9D,KAAO,GAAkC,aAAiB,MAAQ,CAAC,OAAO,MAAM,EAAM,QAAQ,CAAC,EAC/F,KAAO,GAA6C,OAAO,GAAU,UAAY,OAAO,GAAU,SAClG,KAAO,GACH,OAAO,GAAU,UAAY,OAAO,cAAc,CAAK,GAAK,GAAS,GAAK,GAAA,MAC9E,MAAQ,GAAoC,OAAO,GAAU,UAAY,EAAS,KAAK,CAAK,CAChG"}

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

@@ -1 +1 @@
-{"version":3,"file":"ValueConverter.cjs","names":["Validator","EnvaptError","BuiltInConverters","state"],"sources":["../../../src/converters/ValueConverter.ts"],"sourcesContent":["import { BuiltInConverters } from './BuiltInConverters';\nimport { state } from '../core/state';\nimport { Validator } from '../engine/Validators';\nimport { debugVerbose } from '../infra/Debug';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { ArrayOf } from './Converters';\nimport type { StandardSchemaV1 } from '../infra/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 | 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 | undefined {\n        Validator.builtInConverter(resolvedConverter);\n\n        if (hasFallback && !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 undefined;\n            // coerce a string fallback to the number return type through the time converter\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 converted = converterFn(parsed, undefined);\n\n        if (converted === undefined) {\n            // key and type only, no value, since env values can be secrets and verbose logs reach stderr\n            debugVerbose(\n                `could not convert ${formatKeyForError(key)} as ${resolvedConverter}${hasFallback ? ', using the fallback' : ''}`\n            );\n            // re-run with the real fallback so time's string-form fallback still coerces to a number\n            return hasFallback ? (converterFn(parsed, fallback) as TFallback) : undefined;\n        }\n\n        return converted as TFallback;\n    }\n\n    private processArrayConverter<TFallback>(\n        key: EnvKeyInput,\n        fallback: TFallback | undefined,\n        resolvedConverter: ArrayOf,\n        hasFallback: boolean\n    ): TFallback | undefined {\n        Validator.arrayConverter(resolvedConverter);\n\n        if (hasFallback && !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 undefined;\n            // coerce each time-string entry through the time converter so the array is number[]\n            // 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, state.strict);\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 // unused. the custom converter runs even when raw is undefined\n    ): TFallback | 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.cjs","names":["Validator","EnvaptError","BuiltInConverters","state"],"sources":["../../../src/converters/ValueConverter.ts"],"sourcesContent":["import { BuiltInConverters } from './BuiltInConverters';\nimport { state } from '../core/state';\nimport { Validator } from '../engine/Validators';\nimport { debugVerbose } from '../infra/Debug';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { ArrayOf } from './Converters';\nimport type { StandardSchemaV1 } from '../infra/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\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 | 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 | undefined {\n        Validator.builtInConverter(resolvedConverter);\n\n        if (hasFallback && !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 undefined;\n            // time returns a number even when the fallback is a string\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 converted = converterFn(parsed, undefined);\n\n        if (converted === undefined) {\n            // leave the value out because env values can be secrets\n            debugVerbose(\n                `could not convert ${formatKeyForError(key)} as ${resolvedConverter}${hasFallback ? ', using the fallback' : ''}`\n            );\n            // time needs the real fallback to turn a string fallback into a number\n            return hasFallback ? (converterFn(parsed, fallback) as TFallback) : undefined;\n        }\n\n        return converted as TFallback;\n    }\n\n    private processArrayConverter<TFallback>(\n        key: EnvKeyInput,\n        fallback: TFallback | undefined,\n        resolvedConverter: ArrayOf,\n        hasFallback: boolean\n    ): TFallback | undefined {\n        Validator.arrayConverter(resolvedConverter);\n\n        if (hasFallback && !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 undefined;\n            // a time array returns number[] even when its fallback holds strings\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, state.strict);\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 // unused. the custom converter runs even when raw is undefined\n    ): TFallback | 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    // the decorators and `Envapter.parse()` both run schema reads through here\n    convertWithSchema(key: EnvKeyInput, schema: StandardSchemaV1, fallback: unknown, hasFallback: boolean): unknown {\n        const raw = this.envService.get(key, undefined);\n\n        if (raw === undefined) {\n            if (hasFallback) return fallback;\n            throw new EnvaptError(\n                EnvaptErrorCodes.MissingEnvValue,\n                `Required environment variable \"${formatKeyForError(key)}\" is missing or empty.`\n            );\n        }\n\n        let outcome: StandardSchemaV1.Result<unknown> | Promise<StandardSchemaV1.Result<unknown>>;\n        try {\n            outcome = schema['~standard'].validate(raw);\n        } catch (cause) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.SchemaThrew,\n                `Schema for \"${formatKeyForError(key)}\" threw during validation: ${(cause as Error).message}`,\n                { cause }\n            );\n        }\n\n        if (outcome instanceof Promise) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidUserDefinedConfig,\n                `Schema for \"${formatKeyForError(key)}\" returned a Promise. envapt requires synchronous schemas; use a sync validator or perform async checks outside the env layer.`\n            );\n        }\n\n        if (outcome.issues !== undefined) {\n            const first = outcome.issues[0];\n            const firstMessage = first?.message ?? 'no issue message';\n            throw new EnvaptError(\n                EnvaptErrorCodes.SchemaValidationFailed,\n                `Schema validation failed for \"${formatKeyForError(key)}\": ${firstMessage}`,\n                { issues: outcome.issues }\n            );\n        }\n\n        return outcome.value;\n    }\n}\n"],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"ValueConverter.mjs","names":[],"sources":["../../../src/converters/ValueConverter.ts"],"sourcesContent":["import { BuiltInConverters } from './BuiltInConverters';\nimport { state } from '../core/state';\nimport { Validator } from '../engine/Validators';\nimport { debugVerbose } from '../infra/Debug';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { ArrayOf } from './Converters';\nimport type { StandardSchemaV1 } from '../infra/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 | 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 | undefined {\n        Validator.builtInConverter(resolvedConverter);\n\n        if (hasFallback && !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 undefined;\n            // coerce a string fallback to the number return type through the time converter\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 converted = converterFn(parsed, undefined);\n\n        if (converted === undefined) {\n            // key and type only, no value, since env values can be secrets and verbose logs reach stderr\n            debugVerbose(\n                `could not convert ${formatKeyForError(key)} as ${resolvedConverter}${hasFallback ? ', using the fallback' : ''}`\n            );\n            // re-run with the real fallback so time's string-form fallback still coerces to a number\n            return hasFallback ? (converterFn(parsed, fallback) as TFallback) : undefined;\n        }\n\n        return converted as TFallback;\n    }\n\n    private processArrayConverter<TFallback>(\n        key: EnvKeyInput,\n        fallback: TFallback | undefined,\n        resolvedConverter: ArrayOf,\n        hasFallback: boolean\n    ): TFallback | undefined {\n        Validator.arrayConverter(resolvedConverter);\n\n        if (hasFallback && !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 undefined;\n            // coerce each time-string entry through the time converter so the array is number[]\n            // 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, state.strict);\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 // unused. the custom converter runs even when raw is undefined\n    ): TFallback | 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 { state } from '../core/state';\nimport { Validator } from '../engine/Validators';\nimport { debugVerbose } from '../infra/Debug';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { ArrayOf } from './Converters';\nimport type { StandardSchemaV1 } from '../infra/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\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 | 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 | undefined {\n        Validator.builtInConverter(resolvedConverter);\n\n        if (hasFallback && !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 undefined;\n            // time returns a number even when the fallback is a string\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 converted = converterFn(parsed, undefined);\n\n        if (converted === undefined) {\n            // leave the value out because env values can be secrets\n            debugVerbose(\n                `could not convert ${formatKeyForError(key)} as ${resolvedConverter}${hasFallback ? ', using the fallback' : ''}`\n            );\n            // time needs the real fallback to turn a string fallback into a number\n            return hasFallback ? (converterFn(parsed, fallback) as TFallback) : undefined;\n        }\n\n        return converted as TFallback;\n    }\n\n    private processArrayConverter<TFallback>(\n        key: EnvKeyInput,\n        fallback: TFallback | undefined,\n        resolvedConverter: ArrayOf,\n        hasFallback: boolean\n    ): TFallback | undefined {\n        Validator.arrayConverter(resolvedConverter);\n\n        if (hasFallback && !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 undefined;\n            // a time array returns number[] even when its fallback holds strings\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, state.strict);\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 // unused. the custom converter runs even when raw is undefined\n    ): TFallback | 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    // the decorators and `Envapter.parse()` both run schema reads through here\n    convertWithSchema(key: EnvKeyInput, schema: StandardSchemaV1, fallback: unknown, hasFallback: boolean): unknown {\n        const raw = this.envService.get(key, undefined);\n\n        if (raw === undefined) {\n            if (hasFallback) return fallback;\n            throw new EnvaptError(\n                EnvaptErrorCodes.MissingEnvValue,\n                `Required environment variable \"${formatKeyForError(key)}\" is missing or empty.`\n            );\n        }\n\n        let outcome: StandardSchemaV1.Result<unknown> | Promise<StandardSchemaV1.Result<unknown>>;\n        try {\n            outcome = schema['~standard'].validate(raw);\n        } catch (cause) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.SchemaThrew,\n                `Schema for \"${formatKeyForError(key)}\" threw during validation: ${(cause as Error).message}`,\n                { cause }\n            );\n        }\n\n        if (outcome instanceof Promise) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidUserDefinedConfig,\n                `Schema for \"${formatKeyForError(key)}\" returned a Promise. envapt requires synchronous schemas; use a sync validator or perform async checks outside the env layer.`\n            );\n        }\n\n        if (outcome.issues !== undefined) {\n            const first = outcome.issues[0];\n            const firstMessage = first?.message ?? 'no issue message';\n            throw new EnvaptError(\n                EnvaptErrorCodes.SchemaValidationFailed,\n                `Schema validation failed for \"${formatKeyForError(key)}\": ${firstMessage}`,\n                { issues: outcome.issues }\n            );\n        }\n\n        return outcome.value;\n    }\n}\n"],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"AdvancedMethods.cjs","names":["isMissing","PrimitiveMethods","resolveKeyInput","hasFallback","valueConverter","templateResolver","EnvaptError","recase"],"sources":["../../../src/core/AdvancedMethods.ts"],"sourcesContent":["import { resolveKeyInput, templateResolver, valueConverter } from './engine';\nimport { hasFallback, isMissing } from './missing';\nimport { PrimitiveMethods } from './PrimitiveMethods';\nimport { debugWarn } from '../infra/Debug';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\nimport { recase } from '../infra/recase';\n\nimport type { ArrayOf } from '../converters';\nimport type { TemplateResolver } from '../engine/TemplateResolver';\nimport type { InferSchemaOutput, StandardSchemaV1 } from '../infra/StandardSchema';\nimport type {\n    AdvancedConverterReturn,\n    BuiltInConverter,\n    ConditionalReturn,\n    ConverterFunction,\n    EnvaptConverter,\n    EnvKeyInput,\n    InferConverterReturnType,\n    InferSpecField,\n    KeyCasing,\n    RecaseKey,\n    RequiredSpec,\n    SchemaConstraint,\n    TimeFallback\n} from '../types';\n\nfunction formatKeyForError(key: EnvKeyInput): string {\n    return Array.isArray(key) ? `[${key.join(', ')}]` : String(key);\n}\n\n// missing check runs after template resolution so a value that resolves to blank falls through\n// (empty always, whitespace-only under strict)\nexport function resolveRequired(\n    resolved: { key: string; value: string | undefined },\n    templateResolver: TemplateResolver\n): { key: string; value: string | undefined } {\n    if (resolved.value === undefined) return resolved;\n    const value = templateResolver.resolveTemplate(resolved.key, resolved.value);\n    return { key: resolved.key, value: isMissing(value) ? undefined : value };\n}\n\n/**\n * Mixin for advanced methods for environment variable conversion using built-in and custom converters\n * @internal\n */\nexport class AdvancedMethods extends PrimitiveMethods {\n    /**\n     * Get an environment variable using a built-in converter.\n     *\n     * Supports both scalar tokens (e.g. `Converters.Number`) and `ArrayOf<...>` tokens\n     * produced by `Converters.array(...)`. The key can be a single name or an ordered list.\n     * The first defined value wins.\n     * @see {@link https://envapt.materwelon.dev/docs/envapter#converters}\n     * @see {@link https://envapt.materwelon.dev/docs/converters#custom-converters}\n     */\n    // Time-specific overload must precede the generic BuiltInConverter overload so it wins\n    // overload resolution (TimeFallback accepts time-strings like `'10s'`).\n    static getUsing<TFallback extends TimeFallback | undefined = undefined>(\n        key: EnvKeyInput,\n        converter: 'time',\n        fallback?: TFallback\n    ): ConditionalReturn<number, TFallback>;\n    static getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(\n        key: EnvKeyInput,\n        converter: TConverter,\n        fallback?: TFallback\n    ): AdvancedConverterReturn<TConverter, TFallback>;\n    static getUsing<TReturn>(key: EnvKeyInput, converter: BuiltInConverter | ArrayOf, fallback?: TReturn): TReturn;\n    static getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(\n        key: EnvKeyInput,\n        converter: TConverter,\n        fallback?: TFallback\n    ): AdvancedConverterReturn<TConverter, TFallback> {\n        const { key: resolvedKey, value } = resolveKeyInput(key);\n\n        // a missing value with a fallback falls through to the parser so asymmetric types\n        // (TimeFallback, TimeFallback[] for `of: time`) coerce to the return type\n        if (isMissing(value) && !hasFallback(fallback)) {\n            debugWarn(`${resolvedKey} is missing or empty`);\n            return undefined as AdvancedConverterReturn<TConverter, TFallback>;\n        }\n\n        const result = valueConverter.convertValue(resolvedKey, fallback, converter, hasFallback(fallback));\n\n        return result as AdvancedConverterReturn<TConverter, TFallback>;\n    }\n\n    /**\n     * @see {@link AdvancedMethods.getUsing}\n     */\n    getUsing<TFallback extends TimeFallback | undefined = undefined>(\n        key: EnvKeyInput,\n        converter: 'time',\n        fallback?: TFallback\n    ): ConditionalReturn<number, TFallback>;\n    getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(\n        key: EnvKeyInput,\n        converter: TConverter,\n        fallback?: TFallback\n    ): AdvancedConverterReturn<TConverter, TFallback>;\n    getUsing<TReturn>(key: EnvKeyInput, converter: BuiltInConverter | ArrayOf, fallback?: TReturn): TReturn;\n    getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(\n        key: EnvKeyInput,\n        converter: TConverter,\n        fallback?: TFallback\n    ): AdvancedConverterReturn<TConverter, TFallback> {\n        return AdvancedMethods.getUsing(key, converter, fallback);\n    }\n\n    /**\n     * Get an environment variable using a custom converter function.\n     * Accepts a single key or an ordered list for automatic fallback.\n     * @see {@link https://envapt.materwelon.dev/docs/envapter#converters}\n     * @see {@link https://envapt.materwelon.dev/docs/converters#custom-converters}\n     */\n    static getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(\n        key: EnvKeyInput,\n        converter: ConverterFunction<TReturnType>,\n        fallback?: TFallback\n    ): ConditionalReturn<TReturnType, TFallback> {\n        // run the custom converter even on a missing value, with raw as undefined\n        const result = valueConverter.convertValue<TReturnType>(key, fallback, converter, hasFallback(fallback));\n\n        return result as ConditionalReturn<TReturnType, TFallback>;\n    }\n\n    /**\n     * @see {@link AdvancedMethods.getWith}\n     */\n    getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(\n        key: EnvKeyInput,\n        converter: ConverterFunction<TReturnType>,\n        fallback?: TFallback\n    ): ConditionalReturn<TReturnType, TFallback> {\n        return AdvancedMethods.getWith(key, converter, fallback);\n    }\n\n    /**\n     * Read a required environment variable and convert it, throwing `MissingEnvValue` when the value\n     * is missing or empty. Returns the non-undefined converter output. Accepts a built-in or `ArrayOf`\n     * token, or a custom parser function. The key can be a single name or an ordered list.\n     * @see {@link https://envapt.materwelon.dev/docs/envapter#fail-fast-on-missing-values}\n     * @see {@link https://envapt.materwelon.dev/docs/converters#require-a-converted-value}\n     */\n    static getRequired<TConverter extends BuiltInConverter | ArrayOf>(\n        key: EnvKeyInput,\n        converter: TConverter\n    ): InferConverterReturnType<TConverter>;\n    static getRequired<TReturnType>(key: EnvKeyInput, converter: ConverterFunction<TReturnType, string>): TReturnType;\n    static getRequired<TConverter extends BuiltInConverter | ArrayOf, TReturnType>(\n        key: EnvKeyInput,\n        converter: TConverter | ConverterFunction<TReturnType, string>\n    ): InferConverterReturnType<TConverter> | TReturnType {\n        // a required read treats empty as missing, so an empty value falls through to the next candidate.\n        const candidates: readonly string[] = typeof key === 'string' ? [key] : key;\n        let resolvedKey = '';\n        let value: string | undefined;\n        for (const candidate of candidates) {\n            const resolved = resolveRequired(resolveKeyInput(candidate), templateResolver);\n            resolvedKey = resolved.key;\n            if (resolved.value !== undefined) {\n                value = resolved.value;\n                break;\n            }\n        }\n        if (value === undefined) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.MissingEnvValue,\n                `Required environment variable \"${formatKeyForError(key)}\" is missing or empty.`\n            );\n        }\n        // cast widens the raw-string parser back to convertValue's ConverterFunction<T> (value proven present above).\n        const result = valueConverter.convertValue<TReturnType>(\n            resolvedKey,\n            undefined,\n            converter as EnvaptConverter<TReturnType>,\n            false\n        );\n        // a built-in yields undefined for a present value it cannot convert, a custom converter can return null, both break the non-undefined return\n        if (result === undefined || result === null) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.MissingEnvValue,\n                `Required environment variable \"${formatKeyForError(key)}\" is present but could not be converted.`\n            );\n        }\n        return result;\n    }\n\n    /**\n     * @see {@link AdvancedMethods.getRequired}\n     */\n    getRequired<TConverter extends BuiltInConverter | ArrayOf>(\n        key: EnvKeyInput,\n        converter: TConverter\n    ): InferConverterReturnType<TConverter>;\n    getRequired<TReturnType>(key: EnvKeyInput, converter: ConverterFunction<TReturnType, string>): TReturnType;\n    getRequired<TConverter extends BuiltInConverter | ArrayOf, TReturnType>(\n        key: EnvKeyInput,\n        converter: TConverter | ConverterFunction<TReturnType, string>\n    ): InferConverterReturnType<TConverter> | TReturnType {\n        return AdvancedMethods.getRequired(key, converter as ConverterFunction<TReturnType, string>);\n    }\n\n    /**\n     * Read a group of required environment variables in one call. Each key in `spec` maps to a\n     * converter (a token, an `array()` token, or a custom parser), and the returned record holds\n     * every converted value, all non-undefined. Collects every missing or empty key and throws one\n     * `MissingEnvValue` listing them all. Pass a `casing` (`'camelCase'`, `'PascalCase'`, or\n     * `'kebab-case'`) to rename the record keys, splitting on underscores, which assumes the\n     * conventional SCREAMING_SNAKE env-var names. With no casing the keys stay as-is.\n     * @see {@link https://envapt.materwelon.dev/docs/envapter#fail-fast-on-missing-values}\n     * @see {@link https://envapt.materwelon.dev/docs/converters#require-a-converted-value}\n     */\n    static getRequiredAll<Spec extends RequiredSpec, Casing extends KeyCasing | undefined = undefined>(\n        spec: Spec,\n        casing?: Casing\n    ): { [K in keyof Spec as RecaseKey<K & string, Casing>]: InferSpecField<Spec[K]> } {\n        const keys = Object.keys(spec);\n        const missing = keys.filter(\n            (key) => resolveRequired(resolveKeyInput(key), templateResolver).value === undefined\n        );\n        if (missing.length > 0) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.MissingEnvValue,\n                `Missing required environment variables: ${missing.join(', ')}.`\n            );\n        }\n\n        const result: Record<string, unknown> = {};\n        for (const key of keys) {\n            // same widening cast as getRequired, every value was proven present above.\n            const converted = valueConverter.convertValue<unknown>(\n                key,\n                undefined,\n                spec[key] as EnvaptConverter<unknown>,\n                false\n            );\n            if (converted === undefined || converted === null) {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.MissingEnvValue,\n                    `Required environment variable \"${key}\" is present but could not be converted.`\n                );\n            }\n            result[recase(key, casing)] = converted;\n        }\n        return result as { [K in keyof Spec as RecaseKey<K & string, Casing>]: InferSpecField<Spec[K]> };\n    }\n\n    /**\n     * @see {@link AdvancedMethods.getRequiredAll}\n     */\n    getRequiredAll<Spec extends RequiredSpec, Casing extends KeyCasing | undefined = undefined>(\n        spec: Spec,\n        casing?: Casing\n    ): { [K in keyof Spec as RecaseKey<K & string, Casing>]: InferSpecField<Spec[K]> } {\n        return AdvancedMethods.getRequiredAll(spec, casing);\n    }\n\n    /**\n     * Validate an environment variable through a {@link StandardSchemaV1}-conformant schema\n     * (zod, valibot, arktype, etc). Throws `MissingEnvValue` if the env value is absent and\n     * no fallback is provided. The fallback, when provided, is returned as-is on missing.\n     * It does NOT pass through the schema, mirroring custom-converter behavior.\n     *\n     * Synchronous schemas only. A Promise-returning `validate` triggers an\n     * `InvalidUserDefinedConfig` throw at the call site.\n     *\n     * @example\n     * ```ts\n     * import { z } from 'zod';\n     * const port = Envapter.parse('PORT', z.coerce.number().min(1024).max(65535), 3000);\n     * ```\n     * @see {@link https://envapt.materwelon.dev/docs/standard-schema#any-conformant-validator-or-none}\n     */\n    static parse<Schema extends StandardSchemaV1>(\n        key: EnvKeyInput,\n        schema: SchemaConstraint<Schema>,\n        fallback?: InferSchemaOutput<Schema>\n    ): InferSchemaOutput<Schema> {\n        // SchemaConstraint resolves to the unsatisfiable SchemaMustBeSync brand for async\n        // schemas, so reaching this body means the input is structurally a sync Schema.\n        const result = valueConverter.convertWithSchema(\n            key,\n            schema as unknown as StandardSchemaV1,\n            fallback,\n            hasFallback(fallback)\n        );\n        return result;\n    }\n\n    /**\n     * @see {@link AdvancedMethods.parse}\n     */\n    parse<Schema extends StandardSchemaV1>(\n        key: EnvKeyInput,\n        schema: SchemaConstraint<Schema>,\n        fallback?: InferSchemaOutput<Schema>\n    ): InferSchemaOutput<Schema> {\n        const result = valueConverter.convertWithSchema(\n            key,\n            schema as unknown as StandardSchemaV1,\n            fallback,\n            hasFallback(fallback)\n        );\n        return result;\n    }\n}\n"],"mappings":"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"}
+{"version":3,"file":"AdvancedMethods.cjs","names":["isMissing","PrimitiveMethods","resolveKeyInput","hasFallback","valueConverter","templateResolver","EnvaptError","recase"],"sources":["../../../src/core/AdvancedMethods.ts"],"sourcesContent":["import { resolveKeyInput, templateResolver, valueConverter } from './engine';\nimport { hasFallback, isMissing } from './missing';\nimport { PrimitiveMethods } from './PrimitiveMethods';\nimport { debugWarn } from '../infra/Debug';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\nimport { recase } from '../infra/recase';\n\nimport type { ArrayOf } from '../converters';\nimport type { TemplateResolver } from '../engine/TemplateResolver';\nimport type { InferSchemaOutput, StandardSchemaV1 } from '../infra/StandardSchema';\nimport type {\n    AdvancedConverterReturn,\n    BuiltInConverter,\n    ConditionalReturn,\n    ConverterFunction,\n    EnvaptConverter,\n    EnvKeyInput,\n    InferConverterReturnType,\n    InferSpecField,\n    KeyCasing,\n    RecaseKey,\n    RequiredSpec,\n    SchemaConstraint,\n    TimeFallback\n} from '../types';\n\nfunction formatKeyForError(key: EnvKeyInput): string {\n    return Array.isArray(key) ? `[${key.join(', ')}]` : String(key);\n}\n\n// check after template resolution because a template can resolve to an empty string\nexport function resolveRequired(\n    resolved: { key: string; value: string | undefined },\n    templateResolver: TemplateResolver\n): { key: string; value: string | undefined } {\n    if (resolved.value === undefined) return resolved;\n    const value = templateResolver.resolveTemplate(resolved.key, resolved.value);\n    return { key: resolved.key, value: isMissing(value) ? undefined : value };\n}\n\nexport class AdvancedMethods extends PrimitiveMethods {\n    /**\n     * Get an environment variable using a built-in converter.\n     *\n     * Supports both scalar tokens (e.g. `Converters.Number`) and `ArrayOf<...>` tokens\n     * produced by `Converters.array(...)`. The key can be a single name or an ordered list.\n     * The first defined value wins.\n     * @see {@link https://envapt.materwelon.dev/docs/envapter#converters}\n     * @see {@link https://envapt.materwelon.dev/docs/converters#custom-converters}\n     */\n    // TypeScript uses the first overload that matches. Keep 'time' above the generic one.\n    static getUsing<TFallback extends TimeFallback | undefined = undefined>(\n        key: EnvKeyInput,\n        converter: 'time',\n        fallback?: TFallback\n    ): ConditionalReturn<number, TFallback>;\n    static getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(\n        key: EnvKeyInput,\n        converter: TConverter,\n        fallback?: TFallback\n    ): AdvancedConverterReturn<TConverter, TFallback>;\n    static getUsing<TReturn>(key: EnvKeyInput, converter: BuiltInConverter | ArrayOf, fallback?: TReturn): TReturn;\n    static getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(\n        key: EnvKeyInput,\n        converter: TConverter,\n        fallback?: TFallback\n    ): AdvancedConverterReturn<TConverter, TFallback> {\n        const { key: resolvedKey, value } = resolveKeyInput(key);\n\n        // a time fallback can be a string that still needs converting to a number\n        if (isMissing(value) && !hasFallback(fallback)) {\n            debugWarn(`${resolvedKey} is missing or empty`);\n            return undefined as AdvancedConverterReturn<TConverter, TFallback>;\n        }\n\n        const result = valueConverter.convertValue(resolvedKey, fallback, converter, hasFallback(fallback));\n\n        return result as AdvancedConverterReturn<TConverter, TFallback>;\n    }\n\n    /**\n     * @see {@link AdvancedMethods.getUsing}\n     */\n    getUsing<TFallback extends TimeFallback | undefined = undefined>(\n        key: EnvKeyInput,\n        converter: 'time',\n        fallback?: TFallback\n    ): ConditionalReturn<number, TFallback>;\n    getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(\n        key: EnvKeyInput,\n        converter: TConverter,\n        fallback?: TFallback\n    ): AdvancedConverterReturn<TConverter, TFallback>;\n    getUsing<TReturn>(key: EnvKeyInput, converter: BuiltInConverter | ArrayOf, fallback?: TReturn): TReturn;\n    getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(\n        key: EnvKeyInput,\n        converter: TConverter,\n        fallback?: TFallback\n    ): AdvancedConverterReturn<TConverter, TFallback> {\n        return AdvancedMethods.getUsing(key, converter, fallback);\n    }\n\n    /**\n     * Get an environment variable using a custom converter function.\n     * Accepts a single key or an ordered list for automatic fallback.\n     * @see {@link https://envapt.materwelon.dev/docs/envapter#converters}\n     * @see {@link https://envapt.materwelon.dev/docs/converters#custom-converters}\n     */\n    static getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(\n        key: EnvKeyInput,\n        converter: ConverterFunction<TReturnType>,\n        fallback?: TFallback\n    ): ConditionalReturn<TReturnType, TFallback> {\n        // run the custom converter even on a missing value, with raw as undefined\n        const result = valueConverter.convertValue<TReturnType>(key, fallback, converter, hasFallback(fallback));\n\n        return result as ConditionalReturn<TReturnType, TFallback>;\n    }\n\n    /**\n     * @see {@link AdvancedMethods.getWith}\n     */\n    getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(\n        key: EnvKeyInput,\n        converter: ConverterFunction<TReturnType>,\n        fallback?: TFallback\n    ): ConditionalReturn<TReturnType, TFallback> {\n        return AdvancedMethods.getWith(key, converter, fallback);\n    }\n\n    /**\n     * Read a required environment variable and convert it, throwing `MissingEnvValue` when the value\n     * is missing or empty. Returns the non-undefined converter output. Accepts a built-in or `ArrayOf`\n     * token, or a custom parser function. The key can be a single name or an ordered list.\n     * @see {@link https://envapt.materwelon.dev/docs/envapter#fail-fast-on-missing-values}\n     * @see {@link https://envapt.materwelon.dev/docs/converters#require-a-converted-value}\n     */\n    static getRequired<TConverter extends BuiltInConverter | ArrayOf>(\n        key: EnvKeyInput,\n        converter: TConverter\n    ): InferConverterReturnType<TConverter>;\n    static getRequired<TReturnType>(key: EnvKeyInput, converter: ConverterFunction<TReturnType, string>): TReturnType;\n    static getRequired<TConverter extends BuiltInConverter | ArrayOf, TReturnType>(\n        key: EnvKeyInput,\n        converter: TConverter | ConverterFunction<TReturnType, string>\n    ): InferConverterReturnType<TConverter> | TReturnType {\n        // an empty value falls through to the next key\n        const candidates: readonly string[] = typeof key === 'string' ? [key] : key;\n        let resolvedKey = '';\n        let value: string | undefined;\n        for (const candidate of candidates) {\n            const resolved = resolveRequired(resolveKeyInput(candidate), templateResolver);\n            resolvedKey = resolved.key;\n            if (resolved.value !== undefined) {\n                value = resolved.value;\n                break;\n            }\n        }\n        if (value === undefined) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.MissingEnvValue,\n                `Required environment variable \"${formatKeyForError(key)}\" is missing or empty.`\n            );\n        }\n        // the string-only parser is safe to widen because the value is present\n        const result = valueConverter.convertValue<TReturnType>(\n            resolvedKey,\n            undefined,\n            converter as EnvaptConverter<TReturnType>,\n            false\n        );\n        // a built-in returns undefined when it cannot convert, and a custom converter can return null\n        if (result === undefined || result === null) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.MissingEnvValue,\n                `Required environment variable \"${formatKeyForError(key)}\" is present but could not be converted.`\n            );\n        }\n        return result;\n    }\n\n    /**\n     * @see {@link AdvancedMethods.getRequired}\n     */\n    getRequired<TConverter extends BuiltInConverter | ArrayOf>(\n        key: EnvKeyInput,\n        converter: TConverter\n    ): InferConverterReturnType<TConverter>;\n    getRequired<TReturnType>(key: EnvKeyInput, converter: ConverterFunction<TReturnType, string>): TReturnType;\n    getRequired<TConverter extends BuiltInConverter | ArrayOf, TReturnType>(\n        key: EnvKeyInput,\n        converter: TConverter | ConverterFunction<TReturnType, string>\n    ): InferConverterReturnType<TConverter> | TReturnType {\n        return AdvancedMethods.getRequired(key, converter as ConverterFunction<TReturnType, string>);\n    }\n\n    /**\n     * Read a group of required environment variables in one call. Each key in `spec` maps to a\n     * converter (a token, an `array()` token, or a custom parser), and the returned record holds\n     * every converted value, all non-undefined. Collects every missing or empty key and throws one\n     * `MissingEnvValue` listing them all. Pass a `casing` (`'camelCase'`, `'PascalCase'`, or\n     * `'kebab-case'`) to rename the record keys. The rename splits each key on underscores, as in\n     * SCREAMING_SNAKE env-var names. With no casing the keys stay as-is.\n     * @see {@link https://envapt.materwelon.dev/docs/envapter#fail-fast-on-missing-values}\n     * @see {@link https://envapt.materwelon.dev/docs/converters#require-a-converted-value}\n     */\n    static getRequiredAll<Spec extends RequiredSpec, Casing extends KeyCasing | undefined = undefined>(\n        spec: Spec,\n        casing?: Casing\n    ): { [K in keyof Spec as RecaseKey<K & string, Casing>]: InferSpecField<Spec[K]> } {\n        const keys = Object.keys(spec);\n        const missing = keys.filter(\n            (key) => resolveRequired(resolveKeyInput(key), templateResolver).value === undefined\n        );\n        if (missing.length > 0) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.MissingEnvValue,\n                `Missing required environment variables: ${missing.join(', ')}.`\n            );\n        }\n\n        const result: Record<string, unknown> = {};\n        for (const key of keys) {\n            // safe to widen because every value is present by now\n            const converted = valueConverter.convertValue<unknown>(\n                key,\n                undefined,\n                spec[key] as EnvaptConverter<unknown>,\n                false\n            );\n            if (converted === undefined || converted === null) {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.MissingEnvValue,\n                    `Required environment variable \"${key}\" is present but could not be converted.`\n                );\n            }\n            result[recase(key, casing)] = converted;\n        }\n        return result as { [K in keyof Spec as RecaseKey<K & string, Casing>]: InferSpecField<Spec[K]> };\n    }\n\n    /**\n     * @see {@link AdvancedMethods.getRequiredAll}\n     */\n    getRequiredAll<Spec extends RequiredSpec, Casing extends KeyCasing | undefined = undefined>(\n        spec: Spec,\n        casing?: Casing\n    ): { [K in keyof Spec as RecaseKey<K & string, Casing>]: InferSpecField<Spec[K]> } {\n        return AdvancedMethods.getRequiredAll(spec, casing);\n    }\n\n    /**\n     * Validate an environment variable through a {@link StandardSchemaV1}-conformant schema\n     * (zod, valibot, arktype, etc). Throws `MissingEnvValue` if the env value is absent and\n     * no fallback is provided. When the value is missing, the fallback is returned as-is and does\n     * not pass through the schema.\n     *\n     * Synchronous schemas only. A `validate` that returns a Promise throws `InvalidUserDefinedConfig`.\n     *\n     * @example\n     * ```ts\n     * import { z } from 'zod';\n     * const port = Envapter.parse('PORT', z.coerce.number().min(1024).max(65535), 3000);\n     * ```\n     * @see {@link https://envapt.materwelon.dev/docs/standard-schema#any-conformant-validator-or-none}\n     */\n    static parse<Schema extends StandardSchemaV1>(\n        key: EnvKeyInput,\n        schema: SchemaConstraint<Schema>,\n        fallback?: InferSchemaOutput<Schema>\n    ): InferSchemaOutput<Schema> {\n        // SchemaConstraint rejects async schemas at compile time\n        const result = valueConverter.convertWithSchema(\n            key,\n            schema as unknown as StandardSchemaV1,\n            fallback,\n            hasFallback(fallback)\n        );\n        return result;\n    }\n\n    /**\n     * @see {@link AdvancedMethods.parse}\n     */\n    parse<Schema extends StandardSchemaV1>(\n        key: EnvKeyInput,\n        schema: SchemaConstraint<Schema>,\n        fallback?: InferSchemaOutput<Schema>\n    ): InferSchemaOutput<Schema> {\n        const result = valueConverter.convertWithSchema(\n            key,\n            schema as unknown as StandardSchemaV1,\n            fallback,\n            hasFallback(fallback)\n        );\n        return result;\n    }\n}\n"],"mappings":"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"}