envapt 8.0.0-next.0 → 8.0.0-next.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # envapt
 
+## 8.0.0-next.1
+
+### Major Changes
+
+- 60ba358: Unify the rule for when an environment value counts as missing, and use it in every read path, with the global `strict` flag as its only knob.
+
+    A value is missing when it is unset or an empty string (always), and additionally when it is whitespace-only under `Envapter.strict = true`. This one rule now applies to ordered-key reads, `getRequired` / `getRequiredAll`, `Envapter.require`, the `@Envapt({ required: true })` decorator, environment detection, and `${VAR}` template resolution, so their behavior stays consistent.
+
+    **Breaking changes to APIs that predate v8:**
+
+    - Ordered-key reads skip a present-but-empty candidate. `Envapter.get(['PRIMARY', 'FALLBACK'])` returns `FALLBACK` when `PRIMARY` is set but empty. A single key set to an empty string still resolves as before.
+    - `Envapter.require` and the `@Envapt({ required: true })` decorator keep a whitespace-only value in the default non-strict mode, where they previously treated it as missing.
+    - Environment detection keeps a whitespace-only key under non-strict and skips it under strict, where it previously used the key in both modes.
+
+    Set `Envapter.strict = true` for the old whitespace-is-blank behavior.
+
+### Patch Changes
+
+- 60ba358: Under `Envapter.debug = 'verbose'`, log when a present value cannot be parsed by a built-in converter and the read falls back to its default. This surfaces a malformed value (for example a non-numeric `PORT`) that would otherwise fall back silently.
+- 5be3e5c: Add `@see` links to the docs site on the public API TSDoc, so hovering a reader, converter, source, decorator, or error in an editor links to its documentation page.
+
 ## 8.0.0-next.0
 
 ### Major Changes

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

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

package/dist/node/converters/ValueConverter.cjs

@@ -1,2 +1,2 @@
-const e=require("../infra/Error.cjs"),t=require("./BuiltInConverters.cjs"),n=require("../core/state.cjs"),r=require("../engine/Validators.cjs");function i(e){return Array.isArray(e)?`[${e.join(`, `)}]`:String(e)}var a=class{envService;constructor(e){this.envService=e}convertValue(e,t,n,i){let a=this.resolveConverter(n,t),o=this.processFallbackForConverter(a,t);if(r.Validator.isArrayConverter(a))return this.processArrayConverter(e,o,a,i);if(r.Validator.isPrimitiveConstructor(a)){let t=this.convertPrimitiveToString(a);return this.processBuiltInConverter(e,o,t,i,!0)}return r.Validator.isBuiltInConverter(a)?this.processBuiltInConverter(e,o,a,i,!1):this.processCustomConverter(e,o,a,i)}processFallbackForConverter(e,t){return r.Validator.isPrimitiveConstructor(e)&&t!==void 0?r.Validator.coercePrimitiveFallback(e,t):t}convertPrimitiveToString(t){if(t===String)return`string`;if(t===Number)return`number`;if(t===Boolean)return`boolean`;if(t===BigInt)return`bigint`;if(t===Symbol)return`symbol`;throw new e.EnvaptError(204,`Unknown primitive constructor`)}processBuiltInConverter(e,n,i,a,o){r.Validator.builtInConverter(i),a&&n!==void 0&&!o&&r.Validator.validateBuiltInConverterFallback(i,n);let s=this.envService.get(e,void 0);if(s===void 0)return a?i===`time`&&typeof n==`string`?t.BuiltInConverters.getConverter(i)(``,n):n:null;let c=t.BuiltInConverters.getConverter(i)(s,n);return c===void 0&&!a?null:c}processArrayConverter(i,a,o,s){if(r.Validator.arrayConverter(o),s&&a!==void 0&&!Array.isArray(a))throw new e.EnvaptError(101,`ArrayOf<...> requires that the fallback be an array, got ${typeof a}`);s&&Array.isArray(a)&&(r.Validator.validateArrayFallbackElementTypes(a),r.Validator.validateArrayConverterElementTypeMatch(o.of,a));let c=this.envService.get(i,void 0);if(c===void 0){if(!s)return null;if(o.of===`time`&&Array.isArray(a)&&a.every(e=>typeof e==`string`)){let e=t.BuiltInConverters.getConverter(`time`);return a.map(t=>e(``,t))}return a}return t.BuiltInConverters.processArrayConverter(c,o,n.state.strict)}processCustomConverter(e,t,n,i){return r.Validator.customConvertor(n),n(this.envService.get(e,void 0),t)}resolveConverter(e,t){if(e)return e;let n=typeof t;return n===`number`?`number`:n===`boolean`?`boolean`:n===`bigint`?`bigint`:n===`symbol`?`symbol`:`string`}convertWithSchema(t,n,r,a){let o=this.envService.get(t,void 0);if(o===void 0){if(a)return r;throw new e.EnvaptError(305,`Required environment variable "${i(t)}" is missing or empty.`)}let s;try{s=n[`~standard`].validate(o)}catch(n){throw new e.EnvaptError(209,`Schema for "${i(t)}" threw during validation: ${n.message}`,{cause:n})}if(s instanceof Promise)throw new e.EnvaptError(302,`Schema for "${i(t)}" returned a Promise. envapt requires synchronous schemas; use a sync validator or perform async checks outside the env layer.`);if(s.issues!==void 0){let n=s.issues[0]?.message??`no issue message`;throw new e.EnvaptError(208,`Schema validation failed for "${i(t)}": ${n}`,{issues:s.issues})}return s.value}};exports.ValueConverter=a;
+const e=require("../infra/Error.cjs"),t=require("../core/state.cjs"),n=require("./BuiltInConverters.cjs"),r=require("../engine/Validators.cjs"),i=require("../infra/Debug.cjs");function a(e){return Array.isArray(e)?`[${e.join(`, `)}]`:String(e)}var o=class{envService;constructor(e){this.envService=e}convertValue(e,t,n,i){let a=this.resolveConverter(n,t),o=this.processFallbackForConverter(a,t);if(r.Validator.isArrayConverter(a))return this.processArrayConverter(e,o,a,i);if(r.Validator.isPrimitiveConstructor(a)){let t=this.convertPrimitiveToString(a);return this.processBuiltInConverter(e,o,t,i,!0)}return r.Validator.isBuiltInConverter(a)?this.processBuiltInConverter(e,o,a,i,!1):this.processCustomConverter(e,o,a,i)}processFallbackForConverter(e,t){return r.Validator.isPrimitiveConstructor(e)&&t!==void 0?r.Validator.coercePrimitiveFallback(e,t):t}convertPrimitiveToString(t){if(t===String)return`string`;if(t===Number)return`number`;if(t===Boolean)return`boolean`;if(t===BigInt)return`bigint`;if(t===Symbol)return`symbol`;throw new e.EnvaptError(204,`Unknown primitive constructor`)}processBuiltInConverter(e,t,o,s,c){r.Validator.builtInConverter(o),s&&t!==void 0&&!c&&r.Validator.validateBuiltInConverterFallback(o,t);let l=this.envService.get(e,void 0);if(l===void 0)return s?o===`time`&&typeof t==`string`?n.BuiltInConverters.getConverter(o)(``,t):t:null;let u=n.BuiltInConverters.getConverter(o),d=u(l,void 0);return d===void 0?(i.debugVerbose(`could not convert ${a(e)} as ${o}${s?`, using the fallback`:``}`),s?u(l,t):null):d}processArrayConverter(i,a,o,s){if(r.Validator.arrayConverter(o),s&&a!==void 0&&!Array.isArray(a))throw new e.EnvaptError(101,`ArrayOf<...> requires that the fallback be an array, got ${typeof a}`);s&&Array.isArray(a)&&(r.Validator.validateArrayFallbackElementTypes(a),r.Validator.validateArrayConverterElementTypeMatch(o.of,a));let c=this.envService.get(i,void 0);if(c===void 0){if(!s)return null;if(o.of===`time`&&Array.isArray(a)&&a.every(e=>typeof e==`string`)){let e=n.BuiltInConverters.getConverter(`time`);return a.map(t=>e(``,t))}return a}return n.BuiltInConverters.processArrayConverter(c,o,t.state.strict)}processCustomConverter(e,t,n,i){return r.Validator.customConvertor(n),n(this.envService.get(e,void 0),t)}resolveConverter(e,t){if(e)return e;let n=typeof t;return n===`number`?`number`:n===`boolean`?`boolean`:n===`bigint`?`bigint`:n===`symbol`?`symbol`:`string`}convertWithSchema(t,n,r,i){let o=this.envService.get(t,void 0);if(o===void 0){if(i)return r;throw new e.EnvaptError(305,`Required environment variable "${a(t)}" is missing or empty.`)}let s;try{s=n[`~standard`].validate(o)}catch(n){throw new e.EnvaptError(209,`Schema for "${a(t)}" threw during validation: ${n.message}`,{cause:n})}if(s instanceof Promise)throw new e.EnvaptError(302,`Schema for "${a(t)}" returned a Promise. envapt requires synchronous schemas; use a sync validator or perform async checks outside the env layer.`);if(s.issues!==void 0){let n=s.issues[0]?.message??`no issue message`;throw new e.EnvaptError(208,`Schema validation failed for "${a(t)}": ${n}`,{issues:s.issues})}return s.value}};exports.ValueConverter=o;
 //# sourceMappingURL=ValueConverter.cjs.map

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

package/dist/node/converters/ValueConverter.mjs

@@ -1,2 +1,2 @@
-import{EnvaptError as e}from"../infra/Error.mjs";import{BuiltInConverters as t}from"./BuiltInConverters.mjs";import{state as n}from"../core/state.mjs";import{Validator as r}from"../engine/Validators.mjs";function i(e){return Array.isArray(e)?`[${e.join(`, `)}]`:String(e)}var a=class{envService;constructor(e){this.envService=e}convertValue(e,t,n,i){let a=this.resolveConverter(n,t),o=this.processFallbackForConverter(a,t);if(r.isArrayConverter(a))return this.processArrayConverter(e,o,a,i);if(r.isPrimitiveConstructor(a)){let t=this.convertPrimitiveToString(a);return this.processBuiltInConverter(e,o,t,i,!0)}return r.isBuiltInConverter(a)?this.processBuiltInConverter(e,o,a,i,!1):this.processCustomConverter(e,o,a,i)}processFallbackForConverter(e,t){return r.isPrimitiveConstructor(e)&&t!==void 0?r.coercePrimitiveFallback(e,t):t}convertPrimitiveToString(t){if(t===String)return`string`;if(t===Number)return`number`;if(t===Boolean)return`boolean`;if(t===BigInt)return`bigint`;if(t===Symbol)return`symbol`;throw new e(204,`Unknown primitive constructor`)}processBuiltInConverter(e,n,i,a,o){r.builtInConverter(i),a&&n!==void 0&&!o&&r.validateBuiltInConverterFallback(i,n);let s=this.envService.get(e,void 0);if(s===void 0)return a?i===`time`&&typeof n==`string`?t.getConverter(i)(``,n):n:null;let c=t.getConverter(i)(s,n);return c===void 0&&!a?null:c}processArrayConverter(i,a,o,s){if(r.arrayConverter(o),s&&a!==void 0&&!Array.isArray(a))throw new e(101,`ArrayOf<...> requires that the fallback be an array, got ${typeof a}`);s&&Array.isArray(a)&&(r.validateArrayFallbackElementTypes(a),r.validateArrayConverterElementTypeMatch(o.of,a));let c=this.envService.get(i,void 0);if(c===void 0){if(!s)return null;if(o.of===`time`&&Array.isArray(a)&&a.every(e=>typeof e==`string`)){let e=t.getConverter(`time`);return a.map(t=>e(``,t))}return a}return t.processArrayConverter(c,o,n.strict)}processCustomConverter(e,t,n,i){return r.customConvertor(n),n(this.envService.get(e,void 0),t)}resolveConverter(e,t){if(e)return e;let n=typeof t;return n===`number`?`number`:n===`boolean`?`boolean`:n===`bigint`?`bigint`:n===`symbol`?`symbol`:`string`}convertWithSchema(t,n,r,a){let o=this.envService.get(t,void 0);if(o===void 0){if(a)return r;throw new e(305,`Required environment variable "${i(t)}" is missing or empty.`)}let s;try{s=n[`~standard`].validate(o)}catch(n){throw new e(209,`Schema for "${i(t)}" threw during validation: ${n.message}`,{cause:n})}if(s instanceof Promise)throw new e(302,`Schema for "${i(t)}" returned a Promise. envapt requires synchronous schemas; use a sync validator or perform async checks outside the env layer.`);if(s.issues!==void 0){let n=s.issues[0]?.message??`no issue message`;throw new e(208,`Schema validation failed for "${i(t)}": ${n}`,{issues:s.issues})}return s.value}};export{a as ValueConverter};
+import{EnvaptError as e}from"../infra/Error.mjs";import{state as t}from"../core/state.mjs";import{BuiltInConverters as n}from"./BuiltInConverters.mjs";import{Validator as r}from"../engine/Validators.mjs";import{debugVerbose as i}from"../infra/Debug.mjs";function a(e){return Array.isArray(e)?`[${e.join(`, `)}]`:String(e)}var o=class{envService;constructor(e){this.envService=e}convertValue(e,t,n,i){let a=this.resolveConverter(n,t),o=this.processFallbackForConverter(a,t);if(r.isArrayConverter(a))return this.processArrayConverter(e,o,a,i);if(r.isPrimitiveConstructor(a)){let t=this.convertPrimitiveToString(a);return this.processBuiltInConverter(e,o,t,i,!0)}return r.isBuiltInConverter(a)?this.processBuiltInConverter(e,o,a,i,!1):this.processCustomConverter(e,o,a,i)}processFallbackForConverter(e,t){return r.isPrimitiveConstructor(e)&&t!==void 0?r.coercePrimitiveFallback(e,t):t}convertPrimitiveToString(t){if(t===String)return`string`;if(t===Number)return`number`;if(t===Boolean)return`boolean`;if(t===BigInt)return`bigint`;if(t===Symbol)return`symbol`;throw new e(204,`Unknown primitive constructor`)}processBuiltInConverter(e,t,o,s,c){r.builtInConverter(o),s&&t!==void 0&&!c&&r.validateBuiltInConverterFallback(o,t);let l=this.envService.get(e,void 0);if(l===void 0)return s?o===`time`&&typeof t==`string`?n.getConverter(o)(``,t):t:null;let u=n.getConverter(o),d=u(l,void 0);return d===void 0?(i(`could not convert ${a(e)} as ${o}${s?`, using the fallback`:``}`),s?u(l,t):null):d}processArrayConverter(i,a,o,s){if(r.arrayConverter(o),s&&a!==void 0&&!Array.isArray(a))throw new e(101,`ArrayOf<...> requires that the fallback be an array, got ${typeof a}`);s&&Array.isArray(a)&&(r.validateArrayFallbackElementTypes(a),r.validateArrayConverterElementTypeMatch(o.of,a));let c=this.envService.get(i,void 0);if(c===void 0){if(!s)return null;if(o.of===`time`&&Array.isArray(a)&&a.every(e=>typeof e==`string`)){let e=n.getConverter(`time`);return a.map(t=>e(``,t))}return a}return n.processArrayConverter(c,o,t.strict)}processCustomConverter(e,t,n,i){return r.customConvertor(n),n(this.envService.get(e,void 0),t)}resolveConverter(e,t){if(e)return e;let n=typeof t;return n===`number`?`number`:n===`boolean`?`boolean`:n===`bigint`?`bigint`:n===`symbol`?`symbol`:`string`}convertWithSchema(t,n,r,i){let o=this.envService.get(t,void 0);if(o===void 0){if(i)return r;throw new e(305,`Required environment variable "${a(t)}" is missing or empty.`)}let s;try{s=n[`~standard`].validate(o)}catch(n){throw new e(209,`Schema for "${a(t)}" threw during validation: ${n.message}`,{cause:n})}if(s instanceof Promise)throw new e(302,`Schema for "${a(t)}" returned a Promise. envapt requires synchronous schemas; use a sync validator or perform async checks outside the env layer.`);if(s.issues!==void 0){let n=s.issues[0]?.message??`no issue message`;throw new e(208,`Schema validation failed for "${a(t)}": ${n}`,{issues:s.issues})}return s.value}};export{o as ValueConverter};
 //# sourceMappingURL=ValueConverter.mjs.map

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

package/dist/node/core/AdvancedMethods.cjs

@@ -1,2 +1,2 @@
-const e=require("../infra/Error.cjs"),t=require("../infra/Debug.cjs"),n=require("./engine.cjs"),r=require("./PrimitiveMethods.cjs"),i=require("../infra/recase.cjs");function a(e){return Array.isArray(e)?`[${e.join(`, `)}]`:String(e)}function o(e,t){if(e.value===void 0)return e;let n=t.resolveTemplate(e.key,e.value);return{key:e.key,value:n.trim()===``?void 0:n}}var s=class s extends r.PrimitiveMethods{static getUsing(e,r,i){let{key:a,value:o}=n.resolveKeyInput(e);if(n.treatAsMissing(o)&&i===void 0){t.debugWarn(`${a} is missing or empty`);return}let s=i!==void 0;return n.valueConverter.convertValue(a,i,r,s)}getUsing(e,t,n){return s.getUsing(e,t,n)}static getWith(e,r,i){let{key:a,value:o}=n.resolveKeyInput(e);if(n.treatAsMissing(o))return t.debugWarn(`${a} is missing or empty`),i;let s=i!==void 0;return n.valueConverter.convertValue(a,i,r,s)}getWith(e,t,n){return s.getWith(e,t,n)}static getRequired(t,r){let i=typeof t==`string`?[t]:t,s=``,c;for(let e of i){let t=o(n.resolveKeyInput(e),n.templateResolver);if(s=t.key,t.value!==void 0){c=t.value;break}}if(c===void 0)throw new e.EnvaptError(305,`Required environment variable "${a(t)}" is missing or empty.`);let l=n.valueConverter.convertValue(s,void 0,r,!1);if(l==null)throw new e.EnvaptError(305,`Required environment variable "${a(t)}" is present but could not be converted.`);return l}getRequired(e,t){return s.getRequired(e,t)}static getRequiredAll(t,r){let a=Object.keys(t),s=a.filter(e=>o(n.resolveKeyInput(e),n.templateResolver).value===void 0);if(s.length>0)throw new e.EnvaptError(305,`Missing required environment variables: ${s.join(`, `)}.`);let c={};for(let o of a){let a=n.valueConverter.convertValue(o,void 0,t[o],!1);if(a==null)throw new e.EnvaptError(305,`Required environment variable "${o}" is present but could not be converted.`);c[i.recase(o,r)]=a}return c}getRequiredAll(e,t){return s.getRequiredAll(e,t)}static parse(e,t,r){let i=arguments.length>2;return n.valueConverter.convertWithSchema(e,t,r,i)}parse(e,t,r){let i=arguments.length>2;return n.valueConverter.convertWithSchema(e,t,r,i)}};exports.AdvancedMethods=s,exports.resolveRequired=o;
+const e=require("../infra/Error.cjs"),t=require("./missing.cjs"),n=require("../infra/Debug.cjs"),r=require("./engine.cjs"),i=require("./PrimitiveMethods.cjs"),a=require("../infra/recase.cjs");function o(e){return Array.isArray(e)?`[${e.join(`, `)}]`:String(e)}function s(e,n){if(e.value===void 0)return e;let r=n.resolveTemplate(e.key,e.value);return{key:e.key,value:t.isMissing(r)?void 0:r}}var c=class c extends i.PrimitiveMethods{static getUsing(e,i,a){let{key:o,value:s}=r.resolveKeyInput(e);if(t.isMissing(s)&&a===void 0){n.debugWarn(`${o} is missing or empty`);return}let c=a!==void 0;return r.valueConverter.convertValue(o,a,i,c)}getUsing(e,t,n){return c.getUsing(e,t,n)}static getWith(e,i,a){let{key:o,value:s}=r.resolveKeyInput(e);if(t.isMissing(s))return n.debugWarn(`${o} is missing or empty`),a;let c=a!==void 0;return r.valueConverter.convertValue(o,a,i,c)}getWith(e,t,n){return c.getWith(e,t,n)}static getRequired(t,n){let i=typeof t==`string`?[t]:t,a=``,c;for(let e of i){let t=s(r.resolveKeyInput(e),r.templateResolver);if(a=t.key,t.value!==void 0){c=t.value;break}}if(c===void 0)throw new e.EnvaptError(305,`Required environment variable "${o(t)}" is missing or empty.`);let l=r.valueConverter.convertValue(a,void 0,n,!1);if(l==null)throw new e.EnvaptError(305,`Required environment variable "${o(t)}" is present but could not be converted.`);return l}getRequired(e,t){return c.getRequired(e,t)}static getRequiredAll(t,n){let i=Object.keys(t),o=i.filter(e=>s(r.resolveKeyInput(e),r.templateResolver).value===void 0);if(o.length>0)throw new e.EnvaptError(305,`Missing required environment variables: ${o.join(`, `)}.`);let c={};for(let o of i){let i=r.valueConverter.convertValue(o,void 0,t[o],!1);if(i==null)throw new e.EnvaptError(305,`Required environment variable "${o}" is present but could not be converted.`);c[a.recase(o,n)]=i}return c}getRequiredAll(e,t){return c.getRequiredAll(e,t)}static parse(e,t,n){let i=arguments.length>2;return r.valueConverter.convertWithSchema(e,t,n,i)}parse(e,t,n){let i=arguments.length>2;return r.valueConverter.convertWithSchema(e,t,n,i)}};exports.AdvancedMethods=c,exports.resolveRequired=s;
 //# sourceMappingURL=AdvancedMethods.cjs.map

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

@@ -1 +1 @@
-{"version":3,"file":"AdvancedMethods.cjs","names":["PrimitiveMethods","resolveKeyInput","treatAsMissing","valueConverter","templateResolver","EnvaptError","recase"],"sources":["../../../src/core/AdvancedMethods.ts"],"sourcesContent":["import { resolveKeyInput, templateResolver, treatAsMissing, valueConverter } from './engine';\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// template-resolve a present value, treating a post-trim-empty result as missing regardless of strict.\n// a module function so getRequired/getRequiredAll and Envapter.require share it without exposing it on any subclass.\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: value.trim() === '' ? 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     */\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        // missing with no fallback returns undefined, matching the primitive methods. with a fallback,\n        // route through the parser so asymmetric types (TimeFallback, TimeFallback[] for `of: time`)\n        // coerce to the return type.\n        if (treatAsMissing(value) && fallback === undefined) {\n            debugWarn(`${resolvedKey} is missing or empty`);\n            return undefined as AdvancedConverterReturn<TConverter, TFallback>;\n        }\n\n        const hasFallback = fallback !== undefined;\n        const result = valueConverter.convertValue(resolvedKey, fallback, converter, hasFallback);\n\n        return result as AdvancedConverterReturn<TConverter, TFallback>;\n    }\n\n    /**\n     * @see {@link AdvancedMethods.getUsing}\n     */\n    getUsing<TFallback extends TimeFallback | undefined = undefined>(\n        key: EnvKeyInput,\n        converter: 'time',\n        fallback?: TFallback\n    ): ConditionalReturn<number, TFallback>;\n    getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(\n        key: EnvKeyInput,\n        converter: TConverter,\n        fallback?: TFallback\n    ): AdvancedConverterReturn<TConverter, TFallback>;\n    getUsing<TReturn>(key: EnvKeyInput, converter: BuiltInConverter | ArrayOf, fallback?: TReturn): TReturn;\n    getUsing<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     */\n    static getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(\n        key: EnvKeyInput,\n        converter: ConverterFunction<TReturnType>,\n        fallback?: TFallback\n    ): ConditionalReturn<TReturnType, TFallback> {\n        const { key: resolvedKey, value } = resolveKeyInput(key);\n        if (treatAsMissing(value)) {\n            debugWarn(`${resolvedKey} is missing or empty`);\n            return fallback as ConditionalReturn<TReturnType, TFallback>;\n        }\n\n        const hasFallback = fallback !== undefined;\n        const result = valueConverter.convertValue<TReturnType>(resolvedKey, fallback, converter, hasFallback);\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     */\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        // convertValue returns null for a present value it can't convert, which would 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     */\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     */\n    static parse<Schema extends StandardSchemaV1>(\n        key: EnvKeyInput,\n        schema: SchemaConstraint<Schema>,\n        fallback?: InferSchemaOutput<Schema>\n    ): InferSchemaOutput<Schema> {\n        const hasFallback = arguments.length > 2;\n        // SchemaConstraint resolves to the unsatisfiable SchemaMustBeSync brand for async\n        // schemas, so reaching this body means the input is structurally a sync Schema.\n        const result = valueConverter.convertWithSchema(\n            key,\n            schema as unknown as StandardSchemaV1,\n            fallback,\n            hasFallback\n        );\n        return result;\n    }\n\n    /**\n     * @see {@link AdvancedMethods.parse}\n     */\n    parse<Schema extends StandardSchemaV1>(\n        key: EnvKeyInput,\n        schema: SchemaConstraint<Schema>,\n        fallback?: InferSchemaOutput<Schema>\n    ): InferSchemaOutput<Schema> {\n        const hasFallback = arguments.length > 2;\n        const result = valueConverter.convertWithSchema(\n            key,\n            schema as unknown as StandardSchemaV1,\n            fallback,\n            hasFallback\n        );\n        return result;\n    }\n}\n"],"mappings":"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"}
+{"version":3,"file":"AdvancedMethods.cjs","names":["isMissing","PrimitiveMethods","resolveKeyInput","valueConverter","templateResolver","EnvaptError","recase"],"sources":["../../../src/core/AdvancedMethods.ts"],"sourcesContent":["import { resolveKeyInput, templateResolver, valueConverter } from './engine';\nimport { 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// template-resolve a present value, then apply the shared missing check so a resolved blank falls\n// through (empty always, whitespace-only under strict).\n// a module function so getRequired/getRequiredAll and Envapter.require share it without exposing it on any subclass.\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        // missing with no fallback returns undefined, matching the primitive methods. with a fallback,\n        // route through the parser so asymmetric types (TimeFallback, TimeFallback[] for `of: time`)\n        // coerce to the return type.\n        if (isMissing(value) && fallback === undefined) {\n            debugWarn(`${resolvedKey} is missing or empty`);\n            return undefined as AdvancedConverterReturn<TConverter, TFallback>;\n        }\n\n        const hasFallback = fallback !== undefined;\n        const result = valueConverter.convertValue(resolvedKey, fallback, converter, hasFallback);\n\n        return result as AdvancedConverterReturn<TConverter, TFallback>;\n    }\n\n    /**\n     * @see {@link AdvancedMethods.getUsing}\n     */\n    getUsing<TFallback extends TimeFallback | undefined = undefined>(\n        key: EnvKeyInput,\n        converter: 'time',\n        fallback?: TFallback\n    ): ConditionalReturn<number, TFallback>;\n    getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(\n        key: EnvKeyInput,\n        converter: TConverter,\n        fallback?: TFallback\n    ): AdvancedConverterReturn<TConverter, TFallback>;\n    getUsing<TReturn>(key: EnvKeyInput, converter: BuiltInConverter | ArrayOf, fallback?: TReturn): TReturn;\n    getUsing<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        const { key: resolvedKey, value } = resolveKeyInput(key);\n        if (isMissing(value)) {\n            debugWarn(`${resolvedKey} is missing or empty`);\n            return fallback as ConditionalReturn<TReturnType, TFallback>;\n        }\n\n        const hasFallback = fallback !== undefined;\n        const result = valueConverter.convertValue<TReturnType>(resolvedKey, fallback, converter, hasFallback);\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        // convertValue returns null for a present value it can't convert, which would 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        const hasFallback = arguments.length > 2;\n        // SchemaConstraint resolves to the unsatisfiable SchemaMustBeSync brand for async\n        // schemas, so reaching this body means the input is structurally a sync Schema.\n        const result = valueConverter.convertWithSchema(\n            key,\n            schema as unknown as StandardSchemaV1,\n            fallback,\n            hasFallback\n        );\n        return result;\n    }\n\n    /**\n     * @see {@link AdvancedMethods.parse}\n     */\n    parse<Schema extends StandardSchemaV1>(\n        key: EnvKeyInput,\n        schema: SchemaConstraint<Schema>,\n        fallback?: InferSchemaOutput<Schema>\n    ): InferSchemaOutput<Schema> {\n        const hasFallback = arguments.length > 2;\n        const result = valueConverter.convertWithSchema(\n            key,\n            schema as unknown as StandardSchemaV1,\n            fallback,\n            hasFallback\n        );\n        return result;\n    }\n}\n"],"mappings":"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"}

package/dist/node/core/AdvancedMethods.mjs

@@ -1,2 +1,2 @@
-import{EnvaptError as e}from"../infra/Error.mjs";import{debugWarn as t}from"../infra/Debug.mjs";import{resolveKeyInput as n,templateResolver as r,treatAsMissing as i,valueConverter as a}from"./engine.mjs";import{PrimitiveMethods as o}from"./PrimitiveMethods.mjs";import{recase as s}from"../infra/recase.mjs";function c(e){return Array.isArray(e)?`[${e.join(`, `)}]`:String(e)}function l(e,t){if(e.value===void 0)return e;let n=t.resolveTemplate(e.key,e.value);return{key:e.key,value:n.trim()===``?void 0:n}}var u=class u extends o{static getUsing(e,r,o){let{key:s,value:c}=n(e);if(i(c)&&o===void 0){t(`${s} is missing or empty`);return}let l=o!==void 0;return a.convertValue(s,o,r,l)}getUsing(e,t,n){return u.getUsing(e,t,n)}static getWith(e,r,o){let{key:s,value:c}=n(e);if(i(c))return t(`${s} is missing or empty`),o;let l=o!==void 0;return a.convertValue(s,o,r,l)}getWith(e,t,n){return u.getWith(e,t,n)}static getRequired(t,i){let o=typeof t==`string`?[t]:t,s=``,u;for(let e of o){let t=l(n(e),r);if(s=t.key,t.value!==void 0){u=t.value;break}}if(u===void 0)throw new e(305,`Required environment variable "${c(t)}" is missing or empty.`);let d=a.convertValue(s,void 0,i,!1);if(d==null)throw new e(305,`Required environment variable "${c(t)}" is present but could not be converted.`);return d}getRequired(e,t){return u.getRequired(e,t)}static getRequiredAll(t,i){let o=Object.keys(t),c=o.filter(e=>l(n(e),r).value===void 0);if(c.length>0)throw new e(305,`Missing required environment variables: ${c.join(`, `)}.`);let u={};for(let n of o){let r=a.convertValue(n,void 0,t[n],!1);if(r==null)throw new e(305,`Required environment variable "${n}" is present but could not be converted.`);u[s(n,i)]=r}return u}getRequiredAll(e,t){return u.getRequiredAll(e,t)}static parse(e,t,n){let r=arguments.length>2;return a.convertWithSchema(e,t,n,r)}parse(e,t,n){let r=arguments.length>2;return a.convertWithSchema(e,t,n,r)}};export{u as AdvancedMethods,l as resolveRequired};
+import{EnvaptError as e}from"../infra/Error.mjs";import{isMissing as t}from"./missing.mjs";import{debugWarn as n}from"../infra/Debug.mjs";import{resolveKeyInput as r,templateResolver as i,valueConverter as a}from"./engine.mjs";import{PrimitiveMethods as o}from"./PrimitiveMethods.mjs";import{recase as s}from"../infra/recase.mjs";function c(e){return Array.isArray(e)?`[${e.join(`, `)}]`:String(e)}function l(e,n){if(e.value===void 0)return e;let r=n.resolveTemplate(e.key,e.value);return{key:e.key,value:t(r)?void 0:r}}var u=class u extends o{static getUsing(e,i,o){let{key:s,value:c}=r(e);if(t(c)&&o===void 0){n(`${s} is missing or empty`);return}let l=o!==void 0;return a.convertValue(s,o,i,l)}getUsing(e,t,n){return u.getUsing(e,t,n)}static getWith(e,i,o){let{key:s,value:c}=r(e);if(t(c))return n(`${s} is missing or empty`),o;let l=o!==void 0;return a.convertValue(s,o,i,l)}getWith(e,t,n){return u.getWith(e,t,n)}static getRequired(t,n){let o=typeof t==`string`?[t]:t,s=``,u;for(let e of o){let t=l(r(e),i);if(s=t.key,t.value!==void 0){u=t.value;break}}if(u===void 0)throw new e(305,`Required environment variable "${c(t)}" is missing or empty.`);let d=a.convertValue(s,void 0,n,!1);if(d==null)throw new e(305,`Required environment variable "${c(t)}" is present but could not be converted.`);return d}getRequired(e,t){return u.getRequired(e,t)}static getRequiredAll(t,n){let o=Object.keys(t),c=o.filter(e=>l(r(e),i).value===void 0);if(c.length>0)throw new e(305,`Missing required environment variables: ${c.join(`, `)}.`);let u={};for(let r of o){let i=a.convertValue(r,void 0,t[r],!1);if(i==null)throw new e(305,`Required environment variable "${r}" is present but could not be converted.`);u[s(r,n)]=i}return u}getRequiredAll(e,t){return u.getRequiredAll(e,t)}static parse(e,t,n){let r=arguments.length>2;return a.convertWithSchema(e,t,n,r)}parse(e,t,n){let r=arguments.length>2;return a.convertWithSchema(e,t,n,r)}};export{u as AdvancedMethods,l as resolveRequired};
 //# sourceMappingURL=AdvancedMethods.mjs.map

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

@@ -1 +1 @@
-{"version":3,"file":"AdvancedMethods.mjs","names":[],"sources":["../../../src/core/AdvancedMethods.ts"],"sourcesContent":["import { resolveKeyInput, templateResolver, treatAsMissing, valueConverter } from './engine';\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// template-resolve a present value, treating a post-trim-empty result as missing regardless of strict.\n// a module function so getRequired/getRequiredAll and Envapter.require share it without exposing it on any subclass.\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: value.trim() === '' ? 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     */\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        // missing with no fallback returns undefined, matching the primitive methods. with a fallback,\n        // route through the parser so asymmetric types (TimeFallback, TimeFallback[] for `of: time`)\n        // coerce to the return type.\n        if (treatAsMissing(value) && fallback === undefined) {\n            debugWarn(`${resolvedKey} is missing or empty`);\n            return undefined as AdvancedConverterReturn<TConverter, TFallback>;\n        }\n\n        const hasFallback = fallback !== undefined;\n        const result = valueConverter.convertValue(resolvedKey, fallback, converter, hasFallback);\n\n        return result as AdvancedConverterReturn<TConverter, TFallback>;\n    }\n\n    /**\n     * @see {@link AdvancedMethods.getUsing}\n     */\n    getUsing<TFallback extends TimeFallback | undefined = undefined>(\n        key: EnvKeyInput,\n        converter: 'time',\n        fallback?: TFallback\n    ): ConditionalReturn<number, TFallback>;\n    getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(\n        key: EnvKeyInput,\n        converter: TConverter,\n        fallback?: TFallback\n    ): AdvancedConverterReturn<TConverter, TFallback>;\n    getUsing<TReturn>(key: EnvKeyInput, converter: BuiltInConverter | ArrayOf, fallback?: TReturn): TReturn;\n    getUsing<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     */\n    static getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(\n        key: EnvKeyInput,\n        converter: ConverterFunction<TReturnType>,\n        fallback?: TFallback\n    ): ConditionalReturn<TReturnType, TFallback> {\n        const { key: resolvedKey, value } = resolveKeyInput(key);\n        if (treatAsMissing(value)) {\n            debugWarn(`${resolvedKey} is missing or empty`);\n            return fallback as ConditionalReturn<TReturnType, TFallback>;\n        }\n\n        const hasFallback = fallback !== undefined;\n        const result = valueConverter.convertValue<TReturnType>(resolvedKey, fallback, converter, hasFallback);\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     */\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        // convertValue returns null for a present value it can't convert, which would 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     */\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     */\n    static parse<Schema extends StandardSchemaV1>(\n        key: EnvKeyInput,\n        schema: SchemaConstraint<Schema>,\n        fallback?: InferSchemaOutput<Schema>\n    ): InferSchemaOutput<Schema> {\n        const hasFallback = arguments.length > 2;\n        // SchemaConstraint resolves to the unsatisfiable SchemaMustBeSync brand for async\n        // schemas, so reaching this body means the input is structurally a sync Schema.\n        const result = valueConverter.convertWithSchema(\n            key,\n            schema as unknown as StandardSchemaV1,\n            fallback,\n            hasFallback\n        );\n        return result;\n    }\n\n    /**\n     * @see {@link AdvancedMethods.parse}\n     */\n    parse<Schema extends StandardSchemaV1>(\n        key: EnvKeyInput,\n        schema: SchemaConstraint<Schema>,\n        fallback?: InferSchemaOutput<Schema>\n    ): InferSchemaOutput<Schema> {\n        const hasFallback = arguments.length > 2;\n        const result = valueConverter.convertWithSchema(\n            key,\n            schema as unknown as StandardSchemaV1,\n            fallback,\n            hasFallback\n        );\n        return result;\n    }\n}\n"],"mappings":"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"}
+{"version":3,"file":"AdvancedMethods.mjs","names":[],"sources":["../../../src/core/AdvancedMethods.ts"],"sourcesContent":["import { resolveKeyInput, templateResolver, valueConverter } from './engine';\nimport { 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// template-resolve a present value, then apply the shared missing check so a resolved blank falls\n// through (empty always, whitespace-only under strict).\n// a module function so getRequired/getRequiredAll and Envapter.require share it without exposing it on any subclass.\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        // missing with no fallback returns undefined, matching the primitive methods. with a fallback,\n        // route through the parser so asymmetric types (TimeFallback, TimeFallback[] for `of: time`)\n        // coerce to the return type.\n        if (isMissing(value) && fallback === undefined) {\n            debugWarn(`${resolvedKey} is missing or empty`);\n            return undefined as AdvancedConverterReturn<TConverter, TFallback>;\n        }\n\n        const hasFallback = fallback !== undefined;\n        const result = valueConverter.convertValue(resolvedKey, fallback, converter, hasFallback);\n\n        return result as AdvancedConverterReturn<TConverter, TFallback>;\n    }\n\n    /**\n     * @see {@link AdvancedMethods.getUsing}\n     */\n    getUsing<TFallback extends TimeFallback | undefined = undefined>(\n        key: EnvKeyInput,\n        converter: 'time',\n        fallback?: TFallback\n    ): ConditionalReturn<number, TFallback>;\n    getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(\n        key: EnvKeyInput,\n        converter: TConverter,\n        fallback?: TFallback\n    ): AdvancedConverterReturn<TConverter, TFallback>;\n    getUsing<TReturn>(key: EnvKeyInput, converter: BuiltInConverter | ArrayOf, fallback?: TReturn): TReturn;\n    getUsing<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        const { key: resolvedKey, value } = resolveKeyInput(key);\n        if (isMissing(value)) {\n            debugWarn(`${resolvedKey} is missing or empty`);\n            return fallback as ConditionalReturn<TReturnType, TFallback>;\n        }\n\n        const hasFallback = fallback !== undefined;\n        const result = valueConverter.convertValue<TReturnType>(resolvedKey, fallback, converter, hasFallback);\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        // convertValue returns null for a present value it can't convert, which would 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        const hasFallback = arguments.length > 2;\n        // SchemaConstraint resolves to the unsatisfiable SchemaMustBeSync brand for async\n        // schemas, so reaching this body means the input is structurally a sync Schema.\n        const result = valueConverter.convertWithSchema(\n            key,\n            schema as unknown as StandardSchemaV1,\n            fallback,\n            hasFallback\n        );\n        return result;\n    }\n\n    /**\n     * @see {@link AdvancedMethods.parse}\n     */\n    parse<Schema extends StandardSchemaV1>(\n        key: EnvKeyInput,\n        schema: SchemaConstraint<Schema>,\n        fallback?: InferSchemaOutput<Schema>\n    ): InferSchemaOutput<Schema> {\n        const hasFallback = arguments.length > 2;\n        const result = valueConverter.convertWithSchema(\n            key,\n            schema as unknown as StandardSchemaV1,\n            fallback,\n            hasFallback\n        );\n        return result;\n    }\n}\n"],"mappings":"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"}

package/dist/node/core/EnvapterBase.cjs

@@ -1,2 +1,2 @@
-const e=require("./state.cjs"),t=require("../engine/Validators.cjs"),n=require("../infra/runtime.cjs"),r=require("../infra/Debug.cjs"),i=require("./engine.cjs");var a=class{static set strict(t){e.state.strict=t,i.refreshCache()}static get strict(){return e.state.strict}static set debug(e){r.setDebugLevel(e)}static get debug(){return r.getDebugLevel()}static set syncProcessEnv(n){t.Validator.validateSyncProcessEnv(n);let r=e.state.syncProcessEnv;e.state.syncProcessEnv=n,!r&&n&&e.cache.size>0&&i.mirrorToProcessEnv()}static get syncProcessEnv(){return e.state.syncProcessEnv}static set fileApiMode(n){t.Validator.validateFileApiMode(n),e.state.fileApiMode=n}static get fileApiMode(){return e.state.fileApiMode}static load(){i.ensureLoaded()}static useSource(t){e.state.source=t,n.bindRuntimeFromSource(t),i.refreshCache()}getRaw(e){return i.resolveKeyInput(e).value}};exports.EnvapterBase=a;
+const e=require("./state.cjs"),t=require("../engine/Validators.cjs"),n=require("../infra/runtime.cjs"),r=require("../infra/Debug.cjs"),i=require("./engine.cjs"),a=require("../sources/normalizeSource.cjs");var o=class{static set strict(t){e.state.strict=t,i.refreshCache()}static get strict(){return e.state.strict}static set debug(e){r.setDebugLevel(e)}static get debug(){return r.getDebugLevel()}static set syncProcessEnv(n){t.Validator.validateSyncProcessEnv(n);let r=e.state.syncProcessEnv;e.state.syncProcessEnv=n,!r&&n&&e.cache.size>0&&i.mirrorToProcessEnv()}static get syncProcessEnv(){return e.state.syncProcessEnv}static set fileApiMode(n){t.Validator.validateFileApiMode(n),e.state.fileApiMode=n}static get fileApiMode(){return e.state.fileApiMode}static load(){i.ensureLoaded()}static useSource(t){let r=a.normalizeSource(t);e.state.source=r,n.bindRuntimeFromSource(r),i.refreshCache()}getRaw(e){return i.resolveKeyInput(e).value}};exports.EnvapterBase=o;
 //# sourceMappingURL=EnvapterBase.cjs.map

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

@@ -1 +1 @@
-{"version":3,"file":"EnvapterBase.cjs","names":["state","getDebugLevel","cache","resolveKeyInput"],"sources":["../../../src/core/EnvapterBase.ts"],"sourcesContent":["import { ensureLoaded, mirrorToProcessEnv, refreshCache, resolveKeyInput } from './engine';\nimport { cache, state } from './state';\nimport { Validator } from '../engine/Validators';\nimport { getDebugLevel, setDebugLevel } from '../infra/Debug';\nimport { bindRuntimeFromSource } from '../infra/runtime';\n\nimport type { DebugLevel } from '../infra/Debug';\nimport type { EnvKeyInput, FileApiMode, Source } from '../types';\n\n/** @internal */\nexport abstract class EnvapterBase {\n    /**\n     * Enable or disable strict mode. Default `false`. Setting refreshes the cache so\n     * previously-cached converted values get re-evaluated under the new rule.\n     */\n    static set strict(value: boolean) {\n        state.strict = value;\n        refreshCache();\n    }\n\n    static get strict(): boolean {\n        return state.strict;\n    }\n\n    /**\n     * Set the debug log level. Defaults to `silent`. When unset, reads `ENVAPT_DEBUG` from the\n     * bound source on first access. The setter overrides any env-var value. Output goes to stderr\n     * on Node (the console elsewhere), prefixed with `[envapt]`.\n     */\n    static set debug(level: DebugLevel) {\n        setDebugLevel(level);\n    }\n\n    static get debug(): DebugLevel {\n        return getDebugLevel();\n    }\n\n    /**\n     * Opt-in mirror of dotenv-loaded keys back to `process.env`. Default `false`.\n     *\n     * Only keys the loader actually wrote are mirrored, so collision behavior follows\n     * `envFileOptions.override`: with the default `false`, pre-existing `process.env` values\n     * are preserved. With `true`, the file value wins in both the cache and the mirror.\n     *\n     * Flipping `false → true` mirrors the existing tracked delta immediately (no cache\n     * refresh). Flipping `true → false` is one-way: previously mirrored keys remain in\n     * `process.env` until the process exits.\n     */\n    static set syncProcessEnv(value: boolean) {\n        Validator.validateSyncProcessEnv(value);\n        const previous = state.syncProcessEnv;\n        state.syncProcessEnv = value;\n        if (!previous && value && cache.size > 0) mirrorToProcessEnv();\n    }\n\n    static get syncProcessEnv(): boolean {\n        return state.syncProcessEnv;\n    }\n\n    /**\n     * On the portable build, this controls the filesystem-only config APIs (`envPaths`, `baseDir`,\n     * `envFileOptions`, `configureProfiles`, `resetProfiles`). `'warn'` (the default) warns once and\n     * no-ops, `'throw'` throws {@link EnvaptError} `FileApiUnsupported`. The node build runs these\n     * APIs normally and this value has no effect there.\n     */\n    static set fileApiMode(mode: FileApiMode) {\n        Validator.validateFileApiMode(mode);\n        // no refreshCache, this only gates the portable stubs.\n        state.fileApiMode = mode;\n    }\n\n    static get fileApiMode(): FileApiMode {\n        return state.fileApiMode;\n    }\n\n    /**\n     * Eagerly load the `.env` cascade now instead of lazily on the first read. Idempotent: a no-op\n     * once the cache is built. Useful before mirroring to `process.env` (see {@link syncProcessEnv}),\n     * which is what the `envapt/config` side-effect entry does.\n     */\n    static load(): void {\n        ensureLoaded();\n    }\n\n    /**\n     * Bind the environment {@link Source}. On Node the entry binds {@link FileSource} for you\n     * (a `process.env` snapshot plus the `.env` cascade). On the browser or Workers, pass a\n     * `PortableSource` (or any `Source`) before reading. Clears and rebuilds the cache.\n     */\n    static useSource(source: Source): void {\n        state.source = source;\n        bindRuntimeFromSource(source);\n        refreshCache();\n    }\n\n    /**\n     * Read an environment variable as its raw string, skipping parsing and conversion.\n     */\n    getRaw(key: EnvKeyInput): string | undefined {\n        return resolveKeyInput(key).value;\n    }\n}\n"],"mappings":"iKAUA,IAAsB,EAAtB,KAAmC,CAK/B,WAAW,OAAO,EAAgB,CAC9B,EAAA,MAAM,OAAS,EACf,EAAA,aAAa,CACjB,CAEA,WAAW,QAAkB,CACzB,OAAOA,EAAAA,MAAM,MACjB,CAOA,WAAW,MAAM,EAAmB,CAChC,EAAA,cAAc,CAAK,CACvB,CAEA,WAAW,OAAoB,CAC3B,OAAOC,EAAAA,cAAc,CACzB,CAaA,WAAW,eAAe,EAAgB,CACtC,EAAA,UAAU,uBAAuB,CAAK,EACtC,IAAM,EAAWD,EAAAA,MAAM,eACvB,EAAA,MAAM,eAAiB,EACnB,CAAC,GAAY,GAASE,EAAAA,MAAM,KAAO,GAAG,EAAA,mBAAmB,CACjE,CAEA,WAAW,gBAA0B,CACjC,OAAOF,EAAAA,MAAM,cACjB,CAQA,WAAW,YAAY,EAAmB,CACtC,EAAA,UAAU,oBAAoB,CAAI,EAElC,EAAA,MAAM,YAAc,CACxB,CAEA,WAAW,aAA2B,CAClC,OAAOA,EAAAA,MAAM,WACjB,CAOA,OAAO,MAAa,CAChB,EAAA,aAAa,CACjB,CAOA,OAAO,UAAU,EAAsB,CACnC,EAAA,MAAM,OAAS,EACf,EAAA,sBAAsB,CAAM,EAC5B,EAAA,aAAa,CACjB,CAKA,OAAO,EAAsC,CACzC,OAAOG,EAAAA,gBAAgB,CAAG,CAAC,CAAC,KAChC,CACJ"}
+{"version":3,"file":"EnvapterBase.cjs","names":["state","getDebugLevel","cache","normalizeSource","resolveKeyInput"],"sources":["../../../src/core/EnvapterBase.ts"],"sourcesContent":["import { ensureLoaded, mirrorToProcessEnv, refreshCache, resolveKeyInput } from './engine';\nimport { cache, state } from './state';\nimport { Validator } from '../engine/Validators';\nimport { getDebugLevel, setDebugLevel } from '../infra/Debug';\nimport { bindRuntimeFromSource } from '../infra/runtime';\nimport { normalizeSource } from '../sources/normalizeSource';\n\nimport type { DebugLevel } from '../infra/Debug';\nimport type { EnvKeyInput, FileApiMode, Source } from '../types';\n\n/** @internal */\nexport abstract class EnvapterBase {\n    /**\n     * Enable or disable strict mode. Default `false`. Setting refreshes the cache so\n     * previously-cached converted values get re-evaluated under the new rule.\n     * @see {@link https://envapt.materwelon.dev/docs/strict-mode#what-strict-mode-changes}\n     */\n    static set strict(value: boolean) {\n        state.strict = value;\n        refreshCache();\n    }\n\n    static get strict(): boolean {\n        return state.strict;\n    }\n\n    /**\n     * Set the debug log level. Defaults to `silent`. When unset, reads `ENVAPT_DEBUG` from the\n     * bound source on first access. The setter overrides any env-var value. Output goes to stderr\n     * on Node (the console elsewhere), prefixed with `[envapt]`.\n     * @see {@link https://envapt.materwelon.dev/docs/configuration#debug-logging}\n     */\n    static set debug(level: DebugLevel) {\n        setDebugLevel(level);\n    }\n\n    static get debug(): DebugLevel {\n        return getDebugLevel();\n    }\n\n    /**\n     * Opt-in mirror of dotenv-loaded keys back to `process.env`. Default `false`.\n     *\n     * Only keys the loader actually wrote are mirrored, so collision behavior follows\n     * `envFileOptions.override`: with the default `false`, pre-existing `process.env` values\n     * are preserved. With `true`, the file value wins in both the cache and the mirror.\n     *\n     * Flipping `false → true` mirrors the existing tracked delta immediately (no cache\n     * refresh). Flipping `true → false` is one-way: previously mirrored keys remain in\n     * `process.env` until the process exits.\n     * @see {@link https://envapt.materwelon.dev/docs/configuration#mirroring-to-processenv}\n     */\n    static set syncProcessEnv(value: boolean) {\n        Validator.validateSyncProcessEnv(value);\n        const previous = state.syncProcessEnv;\n        state.syncProcessEnv = value;\n        if (!previous && value && cache.size > 0) mirrorToProcessEnv();\n    }\n\n    static get syncProcessEnv(): boolean {\n        return state.syncProcessEnv;\n    }\n\n    /**\n     * On the portable build, this controls the filesystem-only config APIs (`envPaths`, `baseDir`,\n     * `envFileOptions`, `configureProfiles`, `resetProfiles`). `'warn'` (the default) warns once and\n     * no-ops, `'throw'` throws {@link EnvaptError} `FileApiUnsupported`. The node build runs these\n     * APIs normally and this value has no effect there.\n     * @see {@link https://envapt.materwelon.dev/docs/compatibility#binding-by-runtime}\n     */\n    static set fileApiMode(mode: FileApiMode) {\n        Validator.validateFileApiMode(mode);\n        // no refreshCache, this only gates the portable stubs.\n        state.fileApiMode = mode;\n    }\n\n    static get fileApiMode(): FileApiMode {\n        return state.fileApiMode;\n    }\n\n    /**\n     * Eagerly load the `.env` cascade now instead of lazily on the first read. Idempotent: a no-op\n     * once the cache is built. Useful before mirroring to `process.env` (see {@link syncProcessEnv}),\n     * which is what the `envapt/config` side-effect entry does.\n     * @see {@link https://envapt.materwelon.dev/docs/configuration#which-files-load}\n     */\n    static load(): void {\n        ensureLoaded();\n    }\n\n    /**\n     * Bind the environment {@link Source}. On Node the entry binds {@link FileSource} for you\n     * (a `process.env` snapshot plus the `.env` cascade). On the browser or Workers, pass a\n     * `PortableSource` (or any `Source`) before reading. Pass a `(key) => string | undefined` reader for\n     * a source that reads one key at a time and cannot list its keys. Clears and rebuilds the cache.\n     * @see {@link https://envapt.materwelon.dev/docs/sources#the-providers}\n     */\n    static useSource(source: Source | ((key: string) => string | undefined)): void {\n        const resolved = normalizeSource(source);\n        state.source = resolved;\n        bindRuntimeFromSource(resolved);\n        refreshCache();\n    }\n\n    /**\n     * Read an environment variable as its raw string, skipping parsing and conversion.\n     * @see {@link https://envapt.materwelon.dev/docs/envapter#raw-values}\n     */\n    getRaw(key: EnvKeyInput): string | undefined {\n        return resolveKeyInput(key).value;\n    }\n}\n"],"mappings":"6MAWA,IAAsB,EAAtB,KAAmC,CAM/B,WAAW,OAAO,EAAgB,CAC9B,EAAA,MAAM,OAAS,EACf,EAAA,aAAa,CACjB,CAEA,WAAW,QAAkB,CACzB,OAAOA,EAAAA,MAAM,MACjB,CAQA,WAAW,MAAM,EAAmB,CAChC,EAAA,cAAc,CAAK,CACvB,CAEA,WAAW,OAAoB,CAC3B,OAAOC,EAAAA,cAAc,CACzB,CAcA,WAAW,eAAe,EAAgB,CACtC,EAAA,UAAU,uBAAuB,CAAK,EACtC,IAAM,EAAWD,EAAAA,MAAM,eACvB,EAAA,MAAM,eAAiB,EACnB,CAAC,GAAY,GAASE,EAAAA,MAAM,KAAO,GAAG,EAAA,mBAAmB,CACjE,CAEA,WAAW,gBAA0B,CACjC,OAAOF,EAAAA,MAAM,cACjB,CASA,WAAW,YAAY,EAAmB,CACtC,EAAA,UAAU,oBAAoB,CAAI,EAElC,EAAA,MAAM,YAAc,CACxB,CAEA,WAAW,aAA2B,CAClC,OAAOA,EAAAA,MAAM,WACjB,CAQA,OAAO,MAAa,CAChB,EAAA,aAAa,CACjB,CASA,OAAO,UAAU,EAA8D,CAC3E,IAAM,EAAWG,EAAAA,gBAAgB,CAAM,EACvC,EAAA,MAAM,OAAS,EACf,EAAA,sBAAsB,CAAQ,EAC9B,EAAA,aAAa,CACjB,CAMA,OAAO,EAAsC,CACzC,OAAOC,EAAAA,gBAAgB,CAAG,CAAC,CAAC,KAChC,CACJ"}

package/dist/node/core/EnvapterBase.mjs

@@ -1,2 +1,2 @@
-import{cache as e,state as t}from"./state.mjs";import{Validator as n}from"../engine/Validators.mjs";import{bindRuntimeFromSource as r}from"../infra/runtime.mjs";import{getDebugLevel as i,setDebugLevel as a}from"../infra/Debug.mjs";import{ensureLoaded as o,mirrorToProcessEnv as s,refreshCache as c,resolveKeyInput as l}from"./engine.mjs";var u=class{static set strict(e){t.strict=e,c()}static get strict(){return t.strict}static set debug(e){a(e)}static get debug(){return i()}static set syncProcessEnv(r){n.validateSyncProcessEnv(r);let i=t.syncProcessEnv;t.syncProcessEnv=r,!i&&r&&e.size>0&&s()}static get syncProcessEnv(){return t.syncProcessEnv}static set fileApiMode(e){n.validateFileApiMode(e),t.fileApiMode=e}static get fileApiMode(){return t.fileApiMode}static load(){o()}static useSource(e){t.source=e,r(e),c()}getRaw(e){return l(e).value}};export{u as EnvapterBase};
+import{cache as e,state as t}from"./state.mjs";import{Validator as n}from"../engine/Validators.mjs";import{bindRuntimeFromSource as r}from"../infra/runtime.mjs";import{getDebugLevel as i,setDebugLevel as a}from"../infra/Debug.mjs";import{ensureLoaded as o,mirrorToProcessEnv as s,refreshCache as c,resolveKeyInput as l}from"./engine.mjs";import{normalizeSource as u}from"../sources/normalizeSource.mjs";var d=class{static set strict(e){t.strict=e,c()}static get strict(){return t.strict}static set debug(e){a(e)}static get debug(){return i()}static set syncProcessEnv(r){n.validateSyncProcessEnv(r);let i=t.syncProcessEnv;t.syncProcessEnv=r,!i&&r&&e.size>0&&s()}static get syncProcessEnv(){return t.syncProcessEnv}static set fileApiMode(e){n.validateFileApiMode(e),t.fileApiMode=e}static get fileApiMode(){return t.fileApiMode}static load(){o()}static useSource(e){let n=u(e);t.source=n,r(n),c()}getRaw(e){return l(e).value}};export{d as EnvapterBase};
 //# sourceMappingURL=EnvapterBase.mjs.map

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

@@ -1 +1 @@
-{"version":3,"file":"EnvapterBase.mjs","names":[],"sources":["../../../src/core/EnvapterBase.ts"],"sourcesContent":["import { ensureLoaded, mirrorToProcessEnv, refreshCache, resolveKeyInput } from './engine';\nimport { cache, state } from './state';\nimport { Validator } from '../engine/Validators';\nimport { getDebugLevel, setDebugLevel } from '../infra/Debug';\nimport { bindRuntimeFromSource } from '../infra/runtime';\n\nimport type { DebugLevel } from '../infra/Debug';\nimport type { EnvKeyInput, FileApiMode, Source } from '../types';\n\n/** @internal */\nexport abstract class EnvapterBase {\n    /**\n     * Enable or disable strict mode. Default `false`. Setting refreshes the cache so\n     * previously-cached converted values get re-evaluated under the new rule.\n     */\n    static set strict(value: boolean) {\n        state.strict = value;\n        refreshCache();\n    }\n\n    static get strict(): boolean {\n        return state.strict;\n    }\n\n    /**\n     * Set the debug log level. Defaults to `silent`. When unset, reads `ENVAPT_DEBUG` from the\n     * bound source on first access. The setter overrides any env-var value. Output goes to stderr\n     * on Node (the console elsewhere), prefixed with `[envapt]`.\n     */\n    static set debug(level: DebugLevel) {\n        setDebugLevel(level);\n    }\n\n    static get debug(): DebugLevel {\n        return getDebugLevel();\n    }\n\n    /**\n     * Opt-in mirror of dotenv-loaded keys back to `process.env`. Default `false`.\n     *\n     * Only keys the loader actually wrote are mirrored, so collision behavior follows\n     * `envFileOptions.override`: with the default `false`, pre-existing `process.env` values\n     * are preserved. With `true`, the file value wins in both the cache and the mirror.\n     *\n     * Flipping `false → true` mirrors the existing tracked delta immediately (no cache\n     * refresh). Flipping `true → false` is one-way: previously mirrored keys remain in\n     * `process.env` until the process exits.\n     */\n    static set syncProcessEnv(value: boolean) {\n        Validator.validateSyncProcessEnv(value);\n        const previous = state.syncProcessEnv;\n        state.syncProcessEnv = value;\n        if (!previous && value && cache.size > 0) mirrorToProcessEnv();\n    }\n\n    static get syncProcessEnv(): boolean {\n        return state.syncProcessEnv;\n    }\n\n    /**\n     * On the portable build, this controls the filesystem-only config APIs (`envPaths`, `baseDir`,\n     * `envFileOptions`, `configureProfiles`, `resetProfiles`). `'warn'` (the default) warns once and\n     * no-ops, `'throw'` throws {@link EnvaptError} `FileApiUnsupported`. The node build runs these\n     * APIs normally and this value has no effect there.\n     */\n    static set fileApiMode(mode: FileApiMode) {\n        Validator.validateFileApiMode(mode);\n        // no refreshCache, this only gates the portable stubs.\n        state.fileApiMode = mode;\n    }\n\n    static get fileApiMode(): FileApiMode {\n        return state.fileApiMode;\n    }\n\n    /**\n     * Eagerly load the `.env` cascade now instead of lazily on the first read. Idempotent: a no-op\n     * once the cache is built. Useful before mirroring to `process.env` (see {@link syncProcessEnv}),\n     * which is what the `envapt/config` side-effect entry does.\n     */\n    static load(): void {\n        ensureLoaded();\n    }\n\n    /**\n     * Bind the environment {@link Source}. On Node the entry binds {@link FileSource} for you\n     * (a `process.env` snapshot plus the `.env` cascade). On the browser or Workers, pass a\n     * `PortableSource` (or any `Source`) before reading. Clears and rebuilds the cache.\n     */\n    static useSource(source: Source): void {\n        state.source = source;\n        bindRuntimeFromSource(source);\n        refreshCache();\n    }\n\n    /**\n     * Read an environment variable as its raw string, skipping parsing and conversion.\n     */\n    getRaw(key: EnvKeyInput): string | undefined {\n        return resolveKeyInput(key).value;\n    }\n}\n"],"mappings":"kVAUA,IAAsB,EAAtB,KAAmC,CAK/B,WAAW,OAAO,EAAgB,CAC9B,EAAM,OAAS,EACf,EAAa,CACjB,CAEA,WAAW,QAAkB,CACzB,OAAO,EAAM,MACjB,CAOA,WAAW,MAAM,EAAmB,CAChC,EAAc,CAAK,CACvB,CAEA,WAAW,OAAoB,CAC3B,OAAO,EAAc,CACzB,CAaA,WAAW,eAAe,EAAgB,CACtC,EAAU,uBAAuB,CAAK,EACtC,IAAM,EAAW,EAAM,eACvB,EAAM,eAAiB,EACnB,CAAC,GAAY,GAAS,EAAM,KAAO,GAAG,EAAmB,CACjE,CAEA,WAAW,gBAA0B,CACjC,OAAO,EAAM,cACjB,CAQA,WAAW,YAAY,EAAmB,CACtC,EAAU,oBAAoB,CAAI,EAElC,EAAM,YAAc,CACxB,CAEA,WAAW,aAA2B,CAClC,OAAO,EAAM,WACjB,CAOA,OAAO,MAAa,CAChB,EAAa,CACjB,CAOA,OAAO,UAAU,EAAsB,CACnC,EAAM,OAAS,EACf,EAAsB,CAAM,EAC5B,EAAa,CACjB,CAKA,OAAO,EAAsC,CACzC,OAAO,EAAgB,CAAG,CAAC,CAAC,KAChC,CACJ"}
+{"version":3,"file":"EnvapterBase.mjs","names":[],"sources":["../../../src/core/EnvapterBase.ts"],"sourcesContent":["import { ensureLoaded, mirrorToProcessEnv, refreshCache, resolveKeyInput } from './engine';\nimport { cache, state } from './state';\nimport { Validator } from '../engine/Validators';\nimport { getDebugLevel, setDebugLevel } from '../infra/Debug';\nimport { bindRuntimeFromSource } from '../infra/runtime';\nimport { normalizeSource } from '../sources/normalizeSource';\n\nimport type { DebugLevel } from '../infra/Debug';\nimport type { EnvKeyInput, FileApiMode, Source } from '../types';\n\n/** @internal */\nexport abstract class EnvapterBase {\n    /**\n     * Enable or disable strict mode. Default `false`. Setting refreshes the cache so\n     * previously-cached converted values get re-evaluated under the new rule.\n     * @see {@link https://envapt.materwelon.dev/docs/strict-mode#what-strict-mode-changes}\n     */\n    static set strict(value: boolean) {\n        state.strict = value;\n        refreshCache();\n    }\n\n    static get strict(): boolean {\n        return state.strict;\n    }\n\n    /**\n     * Set the debug log level. Defaults to `silent`. When unset, reads `ENVAPT_DEBUG` from the\n     * bound source on first access. The setter overrides any env-var value. Output goes to stderr\n     * on Node (the console elsewhere), prefixed with `[envapt]`.\n     * @see {@link https://envapt.materwelon.dev/docs/configuration#debug-logging}\n     */\n    static set debug(level: DebugLevel) {\n        setDebugLevel(level);\n    }\n\n    static get debug(): DebugLevel {\n        return getDebugLevel();\n    }\n\n    /**\n     * Opt-in mirror of dotenv-loaded keys back to `process.env`. Default `false`.\n     *\n     * Only keys the loader actually wrote are mirrored, so collision behavior follows\n     * `envFileOptions.override`: with the default `false`, pre-existing `process.env` values\n     * are preserved. With `true`, the file value wins in both the cache and the mirror.\n     *\n     * Flipping `false → true` mirrors the existing tracked delta immediately (no cache\n     * refresh). Flipping `true → false` is one-way: previously mirrored keys remain in\n     * `process.env` until the process exits.\n     * @see {@link https://envapt.materwelon.dev/docs/configuration#mirroring-to-processenv}\n     */\n    static set syncProcessEnv(value: boolean) {\n        Validator.validateSyncProcessEnv(value);\n        const previous = state.syncProcessEnv;\n        state.syncProcessEnv = value;\n        if (!previous && value && cache.size > 0) mirrorToProcessEnv();\n    }\n\n    static get syncProcessEnv(): boolean {\n        return state.syncProcessEnv;\n    }\n\n    /**\n     * On the portable build, this controls the filesystem-only config APIs (`envPaths`, `baseDir`,\n     * `envFileOptions`, `configureProfiles`, `resetProfiles`). `'warn'` (the default) warns once and\n     * no-ops, `'throw'` throws {@link EnvaptError} `FileApiUnsupported`. The node build runs these\n     * APIs normally and this value has no effect there.\n     * @see {@link https://envapt.materwelon.dev/docs/compatibility#binding-by-runtime}\n     */\n    static set fileApiMode(mode: FileApiMode) {\n        Validator.validateFileApiMode(mode);\n        // no refreshCache, this only gates the portable stubs.\n        state.fileApiMode = mode;\n    }\n\n    static get fileApiMode(): FileApiMode {\n        return state.fileApiMode;\n    }\n\n    /**\n     * Eagerly load the `.env` cascade now instead of lazily on the first read. Idempotent: a no-op\n     * once the cache is built. Useful before mirroring to `process.env` (see {@link syncProcessEnv}),\n     * which is what the `envapt/config` side-effect entry does.\n     * @see {@link https://envapt.materwelon.dev/docs/configuration#which-files-load}\n     */\n    static load(): void {\n        ensureLoaded();\n    }\n\n    /**\n     * Bind the environment {@link Source}. On Node the entry binds {@link FileSource} for you\n     * (a `process.env` snapshot plus the `.env` cascade). On the browser or Workers, pass a\n     * `PortableSource` (or any `Source`) before reading. Pass a `(key) => string | undefined` reader for\n     * a source that reads one key at a time and cannot list its keys. Clears and rebuilds the cache.\n     * @see {@link https://envapt.materwelon.dev/docs/sources#the-providers}\n     */\n    static useSource(source: Source | ((key: string) => string | undefined)): void {\n        const resolved = normalizeSource(source);\n        state.source = resolved;\n        bindRuntimeFromSource(resolved);\n        refreshCache();\n    }\n\n    /**\n     * Read an environment variable as its raw string, skipping parsing and conversion.\n     * @see {@link https://envapt.materwelon.dev/docs/envapter#raw-values}\n     */\n    getRaw(key: EnvKeyInput): string | undefined {\n        return resolveKeyInput(key).value;\n    }\n}\n"],"mappings":"mZAWA,IAAsB,EAAtB,KAAmC,CAM/B,WAAW,OAAO,EAAgB,CAC9B,EAAM,OAAS,EACf,EAAa,CACjB,CAEA,WAAW,QAAkB,CACzB,OAAO,EAAM,MACjB,CAQA,WAAW,MAAM,EAAmB,CAChC,EAAc,CAAK,CACvB,CAEA,WAAW,OAAoB,CAC3B,OAAO,EAAc,CACzB,CAcA,WAAW,eAAe,EAAgB,CACtC,EAAU,uBAAuB,CAAK,EACtC,IAAM,EAAW,EAAM,eACvB,EAAM,eAAiB,EACnB,CAAC,GAAY,GAAS,EAAM,KAAO,GAAG,EAAmB,CACjE,CAEA,WAAW,gBAA0B,CACjC,OAAO,EAAM,cACjB,CASA,WAAW,YAAY,EAAmB,CACtC,EAAU,oBAAoB,CAAI,EAElC,EAAM,YAAc,CACxB,CAEA,WAAW,aAA2B,CAClC,OAAO,EAAM,WACjB,CAQA,OAAO,MAAa,CAChB,EAAa,CACjB,CASA,OAAO,UAAU,EAA8D,CAC3E,IAAM,EAAW,EAAgB,CAAM,EACvC,EAAM,OAAS,EACf,EAAsB,CAAQ,EAC9B,EAAa,CACjB,CAMA,OAAO,EAAsC,CACzC,OAAO,EAAgB,CAAG,CAAC,CAAC,KAChC,CACJ"}

package/dist/node/core/Environment.cjs

@@ -1,2 +1,2 @@
-let e=function(e){return e[e.Development=0]=`Development`,e[e.Staging=1]=`Staging`,e[e.Production=2]=`Production`,e[e.Test=3]=`Test`,e}({});const t=[`ENVIRONMENT`,`ENV`,`NODE_ENV`,`MODE`];function n(e){switch(e.toLowerCase()){case`production`:return 2;case`staging`:return 1;case`test`:return 3;case`development`:return 0;default:return}}function r(e){for(let n of t){let t=e(n);if(t!==void 0&&t.length>0)return t}}exports.ENV_KEYS=t,exports.Environment=e,exports.firstEnvKeyValue=r,exports.parseEnvironment=n;
+const e=require("./missing.cjs");let t=function(e){return e[e.Development=0]=`Development`,e[e.Staging=1]=`Staging`,e[e.Production=2]=`Production`,e[e.Test=3]=`Test`,e}({});const n=[`ENVIRONMENT`,`ENV`,`NODE_ENV`,`MODE`];function r(e){switch(e.toLowerCase()){case`production`:return 2;case`staging`:return 1;case`test`:return 3;case`development`:return 0;default:return}}function i(t){for(let r of n){let n=t(r);if(!e.isMissing(n))return n}}exports.ENV_KEYS=n,exports.Environment=t,exports.firstEnvKeyValue=i,exports.parseEnvironment=r;
 //# sourceMappingURL=Environment.cjs.map

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

@@ -1 +1 @@
-{"version":3,"file":"Environment.cjs","names":[],"sources":["../../../src/core/Environment.ts"],"sourcesContent":["/**\n * Environment types supported by Envapter\n *\n * The following keys are checked in order until the first with a non-empty value is found, or defaulting to development if none are set:\n * - `ENVIRONMENT`\n * - `ENV`\n * - `NODE_ENV`\n * - `MODE`\n *\n * @public\n */\nexport enum Environment {\n    /** The default when no environment variable names a known environment. */\n    Development,\n    /** Selected when an environment variable reads `staging`. */\n    Staging,\n    /** Selected when an environment variable reads `production`. */\n    Production,\n    /** Selected when an environment variable reads `test`. */\n    Test\n}\n\n// highest precedence first\nexport const ENV_KEYS = ['ENVIRONMENT', 'ENV', 'NODE_ENV', 'MODE'] as const;\n\nexport function parseEnvironment(raw: string): Environment | undefined {\n    switch (raw.toLowerCase()) {\n        case 'production':\n            return Environment.Production;\n        case 'staging':\n            return Environment.Staging;\n        case 'test':\n            return Environment.Test;\n        case 'development':\n            return Environment.Development;\n        default:\n            return undefined;\n    }\n}\n\nexport function firstEnvKeyValue(read: (key: string) => string | undefined): string | undefined {\n    for (const key of ENV_KEYS) {\n        const value = read(key);\n        if (value !== undefined && value.length > 0) return value;\n    }\n    return undefined;\n}\n"],"mappings":"AAWA,IAAY,EAAL,SAAA,EAAA,OAEH,GAAA,EAAA,YAAA,GAAA,cAEA,EAAA,EAAA,QAAA,GAAA,UAEA,EAAA,EAAA,WAAA,GAAA,aAEA,EAAA,EAAA,KAAA,GAAA,QACJ,EAAA,CAAA,CAAA,EAGA,MAAa,EAAW,CAAC,cAAe,MAAO,WAAY,MAAM,EAEjE,SAAgB,EAAiB,EAAsC,CACnE,OAAQ,EAAI,YAAY,EAAxB,CACI,IAAK,aACD,MAAA,GACJ,IAAK,UACD,MAAA,GACJ,IAAK,OACD,MAAA,GACJ,IAAK,cACD,MAAA,GACJ,QACI,MACR,CACJ,CAEA,SAAgB,EAAiB,EAA+D,CAC5F,IAAK,IAAM,KAAO,EAAU,CACxB,IAAM,EAAQ,EAAK,CAAG,EACtB,GAAI,IAAU,IAAA,IAAa,EAAM,OAAS,EAAG,OAAO,CACxD,CAEJ"}
+{"version":3,"file":"Environment.cjs","names":["isMissing"],"sources":["../../../src/core/Environment.ts"],"sourcesContent":["import { isMissing } from './missing';\n\n/**\n * Environment types supported by Envapter\n *\n * The following keys are checked in order until the first with a present (non-missing) value, defaulting to development if none are set:\n * - `ENVIRONMENT`\n * - `ENV`\n * - `NODE_ENV`\n * - `MODE`\n *\n * @public\n * @see {@link https://envapt.materwelon.dev/docs/environment#detecting-the-environment}\n */\nexport enum Environment {\n    /** The default when no environment variable names a known environment. */\n    Development,\n    /** Selected when an environment variable reads `staging`. */\n    Staging,\n    /** Selected when an environment variable reads `production`. */\n    Production,\n    /** Selected when an environment variable reads `test`. */\n    Test\n}\n\n// highest precedence first\nexport const ENV_KEYS = ['ENVIRONMENT', 'ENV', 'NODE_ENV', 'MODE'] as const;\n\nexport function parseEnvironment(raw: string): Environment | undefined {\n    switch (raw.toLowerCase()) {\n        case 'production':\n            return Environment.Production;\n        case 'staging':\n            return Environment.Staging;\n        case 'test':\n            return Environment.Test;\n        case 'development':\n            return Environment.Development;\n        default:\n            return undefined;\n    }\n}\n\nexport function firstEnvKeyValue(read: (key: string) => string | undefined): string | undefined {\n    for (const key of ENV_KEYS) {\n        const value = read(key);\n        if (!isMissing(value)) return value;\n    }\n    return undefined;\n}\n"],"mappings":"iCAcA,IAAY,EAAL,SAAA,EAAA,OAEH,GAAA,EAAA,YAAA,GAAA,cAEA,EAAA,EAAA,QAAA,GAAA,UAEA,EAAA,EAAA,WAAA,GAAA,aAEA,EAAA,EAAA,KAAA,GAAA,QACJ,EAAA,CAAA,CAAA,EAGA,MAAa,EAAW,CAAC,cAAe,MAAO,WAAY,MAAM,EAEjE,SAAgB,EAAiB,EAAsC,CACnE,OAAQ,EAAI,YAAY,EAAxB,CACI,IAAK,aACD,MAAA,GACJ,IAAK,UACD,MAAA,GACJ,IAAK,OACD,MAAA,GACJ,IAAK,cACD,MAAA,GACJ,QACI,MACR,CACJ,CAEA,SAAgB,EAAiB,EAA+D,CAC5F,IAAK,IAAM,KAAO,EAAU,CACxB,IAAM,EAAQ,EAAK,CAAG,EACtB,GAAI,CAACA,EAAAA,UAAU,CAAK,EAAG,OAAO,CAClC,CAEJ"}

package/dist/node/core/Environment.mjs

@@ -1,2 +1,2 @@
-let e=function(e){return e[e.Development=0]=`Development`,e[e.Staging=1]=`Staging`,e[e.Production=2]=`Production`,e[e.Test=3]=`Test`,e}({});const t=[`ENVIRONMENT`,`ENV`,`NODE_ENV`,`MODE`];function n(e){switch(e.toLowerCase()){case`production`:return 2;case`staging`:return 1;case`test`:return 3;case`development`:return 0;default:return}}function r(e){for(let n of t){let t=e(n);if(t!==void 0&&t.length>0)return t}}export{t as ENV_KEYS,e as Environment,r as firstEnvKeyValue,n as parseEnvironment};
+import{isMissing as e}from"./missing.mjs";let t=function(e){return e[e.Development=0]=`Development`,e[e.Staging=1]=`Staging`,e[e.Production=2]=`Production`,e[e.Test=3]=`Test`,e}({});const n=[`ENVIRONMENT`,`ENV`,`NODE_ENV`,`MODE`];function r(e){switch(e.toLowerCase()){case`production`:return 2;case`staging`:return 1;case`test`:return 3;case`development`:return 0;default:return}}function i(t){for(let r of n){let n=t(r);if(!e(n))return n}}export{n as ENV_KEYS,t as Environment,i as firstEnvKeyValue,r as parseEnvironment};
 //# sourceMappingURL=Environment.mjs.map

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

@@ -1 +1 @@
-{"version":3,"file":"Environment.mjs","names":[],"sources":["../../../src/core/Environment.ts"],"sourcesContent":["/**\n * Environment types supported by Envapter\n *\n * The following keys are checked in order until the first with a non-empty value is found, or defaulting to development if none are set:\n * - `ENVIRONMENT`\n * - `ENV`\n * - `NODE_ENV`\n * - `MODE`\n *\n * @public\n */\nexport enum Environment {\n    /** The default when no environment variable names a known environment. */\n    Development,\n    /** Selected when an environment variable reads `staging`. */\n    Staging,\n    /** Selected when an environment variable reads `production`. */\n    Production,\n    /** Selected when an environment variable reads `test`. */\n    Test\n}\n\n// highest precedence first\nexport const ENV_KEYS = ['ENVIRONMENT', 'ENV', 'NODE_ENV', 'MODE'] as const;\n\nexport function parseEnvironment(raw: string): Environment | undefined {\n    switch (raw.toLowerCase()) {\n        case 'production':\n            return Environment.Production;\n        case 'staging':\n            return Environment.Staging;\n        case 'test':\n            return Environment.Test;\n        case 'development':\n            return Environment.Development;\n        default:\n            return undefined;\n    }\n}\n\nexport function firstEnvKeyValue(read: (key: string) => string | undefined): string | undefined {\n    for (const key of ENV_KEYS) {\n        const value = read(key);\n        if (value !== undefined && value.length > 0) return value;\n    }\n    return undefined;\n}\n"],"mappings":"AAWA,IAAY,EAAL,SAAA,EAAA,OAEH,GAAA,EAAA,YAAA,GAAA,cAEA,EAAA,EAAA,QAAA,GAAA,UAEA,EAAA,EAAA,WAAA,GAAA,aAEA,EAAA,EAAA,KAAA,GAAA,QACJ,EAAA,CAAA,CAAA,EAGA,MAAa,EAAW,CAAC,cAAe,MAAO,WAAY,MAAM,EAEjE,SAAgB,EAAiB,EAAsC,CACnE,OAAQ,EAAI,YAAY,EAAxB,CACI,IAAK,aACD,MAAA,GACJ,IAAK,UACD,MAAA,GACJ,IAAK,OACD,MAAA,GACJ,IAAK,cACD,MAAA,GACJ,QACI,MACR,CACJ,CAEA,SAAgB,EAAiB,EAA+D,CAC5F,IAAK,IAAM,KAAO,EAAU,CACxB,IAAM,EAAQ,EAAK,CAAG,EACtB,GAAI,IAAU,IAAA,IAAa,EAAM,OAAS,EAAG,OAAO,CACxD,CAEJ"}
+{"version":3,"file":"Environment.mjs","names":[],"sources":["../../../src/core/Environment.ts"],"sourcesContent":["import { isMissing } from './missing';\n\n/**\n * Environment types supported by Envapter\n *\n * The following keys are checked in order until the first with a present (non-missing) value, defaulting to development if none are set:\n * - `ENVIRONMENT`\n * - `ENV`\n * - `NODE_ENV`\n * - `MODE`\n *\n * @public\n * @see {@link https://envapt.materwelon.dev/docs/environment#detecting-the-environment}\n */\nexport enum Environment {\n    /** The default when no environment variable names a known environment. */\n    Development,\n    /** Selected when an environment variable reads `staging`. */\n    Staging,\n    /** Selected when an environment variable reads `production`. */\n    Production,\n    /** Selected when an environment variable reads `test`. */\n    Test\n}\n\n// highest precedence first\nexport const ENV_KEYS = ['ENVIRONMENT', 'ENV', 'NODE_ENV', 'MODE'] as const;\n\nexport function parseEnvironment(raw: string): Environment | undefined {\n    switch (raw.toLowerCase()) {\n        case 'production':\n            return Environment.Production;\n        case 'staging':\n            return Environment.Staging;\n        case 'test':\n            return Environment.Test;\n        case 'development':\n            return Environment.Development;\n        default:\n            return undefined;\n    }\n}\n\nexport function firstEnvKeyValue(read: (key: string) => string | undefined): string | undefined {\n    for (const key of ENV_KEYS) {\n        const value = read(key);\n        if (!isMissing(value)) return value;\n    }\n    return undefined;\n}\n"],"mappings":"0CAcA,IAAY,EAAL,SAAA,EAAA,OAEH,GAAA,EAAA,YAAA,GAAA,cAEA,EAAA,EAAA,QAAA,GAAA,UAEA,EAAA,EAAA,WAAA,GAAA,aAEA,EAAA,EAAA,KAAA,GAAA,QACJ,EAAA,CAAA,CAAA,EAGA,MAAa,EAAW,CAAC,cAAe,MAAO,WAAY,MAAM,EAEjE,SAAgB,EAAiB,EAAsC,CACnE,OAAQ,EAAI,YAAY,EAAxB,CACI,IAAK,aACD,MAAA,GACJ,IAAK,UACD,MAAA,GACJ,IAAK,OACD,MAAA,GACJ,IAAK,cACD,MAAA,GACJ,QACI,MACR,CACJ,CAEA,SAAgB,EAAiB,EAA+D,CAC5F,IAAK,IAAM,KAAO,EAAU,CACxB,IAAM,EAAQ,EAAK,CAAG,EACtB,GAAI,CAAC,EAAU,CAAK,EAAG,OAAO,CAClC,CAEJ"}

package/dist/node/core/EnvironmentMethods.cjs

@@ -1,2 +1,2 @@
-require("./Environment.cjs");const e=require("./state.cjs"),t=require("./engine.cjs"),n=require("./EnvapterBase.cjs");var r=class r extends n.EnvapterBase{static get environment(){return e.state.environment===void 0&&t.determineEnvironment(),e.state.environment}static set environment(e){t.determineEnvironment(e)}get environment(){return r.environment}set environment(e){t.determineEnvironment(e)}static get isProduction(){return this.environment===2}get isProduction(){return r.environment===2}static get isStaging(){return this.environment===1}get isStaging(){return r.environment===1}static get isDevelopment(){return this.environment===0}get isDevelopment(){return r.environment===0}static get isTest(){return this.environment===3}get isTest(){return r.environment===3}};exports.EnvironmentMethods=r;
+const e=require("./state.cjs");require("./Environment.cjs");const t=require("./engine.cjs"),n=require("./EnvapterBase.cjs");var r=class r extends n.EnvapterBase{static get environment(){return e.state.environment===void 0&&t.determineEnvironment(),e.state.environment}static set environment(e){t.determineEnvironment(e)}get environment(){return r.environment}set environment(e){t.determineEnvironment(e)}static get isProduction(){return this.environment===2}get isProduction(){return r.environment===2}static get isStaging(){return this.environment===1}get isStaging(){return r.environment===1}static get isDevelopment(){return this.environment===0}get isDevelopment(){return r.environment===0}static get isTest(){return this.environment===3}get isTest(){return r.environment===3}};exports.EnvironmentMethods=r;
 //# sourceMappingURL=EnvironmentMethods.cjs.map