envapt 5.0.2 → 5.1.0

package/dist/converters/Converters.d.mts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"Converters.d.mts","names":[],"sources":["../../src/converters/Converters.ts"],"mappings":";cAAM,MAAA;EAAA;;;;;;;;;;;;;;;;;KAmBM,cAAA,WAAyB,MAAA,eAAqB,MAAM;AAAhE;;;;AAAgE;AAAhE,KAOY,sBAAA,uBAA6C,GAAA,aAAgB,OAAO;;;;;;KAOpE,YAAA,GAAe,OAAA,CAAQ,cAAA,uBAAqC,sBAAA;;AAPQ;AAOhF;;;;UAQiB,OAAA,kBAAyB,YAAA,GAAe,YAAA;EAAA,SAC5C,YAAA;EAAA,SACA,EAAA,EAAI,QAAA;EAAA,SACJ,SAAA;AAAA;;;;AAXiF;iBAkB9E,SAAA,CAAU,KAAA,YAAiB,KAAA,IAAS,OAAO;AAAA,KAStD,kBAAA,GAAqB,OAAO,CAAC,cAAA;AAAA,iBAIzB,mBAAA,SAAA,CAA6B,IAAA;EAClC,EAAA,EAAI,sBAAA,CAAuB,OAAA;EAC3B,SAAA;AAAA,IACA,OAAA,CAAQ,sBAAA,CAAuB,OAAA;AAAA,iBAC1B,mBAAA,gBAAmC,kBAAA,CAAA,CAAoB,IAAA;EAC5D,EAAA,EAAI,MAAA;EACJ,SAAA;AAAA,IACA,OAAA,CAAQ,MAAA;AAAA,iBACH,mBAAA,CAAoB,IAAA;EAAS,SAAA;AAAA,IAAuB,OAAO;;;;AA5B9C;AAOtB;;;;;;;;AAA2D;AAO1D;;cAsCY,UAAA;EAAA,uBAGH,mBAAA;EAAA"}

package/dist/converters/Converters.mjs

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

package/dist/converters/Converters.mjs.map

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

package/dist/converters/ListOfBuiltInConverters.cjs

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

package/dist/converters/ListOfBuiltInConverters.cjs.map

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

package/dist/converters/ListOfBuiltInConverters.mjs

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

package/dist/converters/ListOfBuiltInConverters.mjs.map

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

package/dist/converters/ValueConverter.cjs

@@ -0,0 +1,2 @@
+const e=require("../Error.cjs"),t=require("./BuiltInConverters.cjs"),n=require("../Validators.cjs");function r(e){return Array.isArray(e)?`[${e.join(`, `)}]`:String(e)}var i=class{envService;constructor(e){this.envService=e}convertValue(e,t,r,i){let a=this.resolveConverter(r,t),o=this.processFallbackForConverter(a,t);if(n.Validator.isArrayConverter(a))return this.processArrayConverter(e,o,a,i);if(n.Validator.isPrimitiveConstructor(a)){let t=this.convertPrimitiveToString(a);return this.processBuiltInConverter(e,o,t,i,!0)}return n.Validator.isBuiltInConverter(a)?this.processBuiltInConverter(e,o,a,i,!1):this.processCustomConverter(e,o,a,i)}processFallbackForConverter(e,t){return n.Validator.isPrimitiveConstructor(e)&&t!==void 0?n.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,r,i,a,o){n.Validator.builtInConverter(i),a&&r!==void 0&&!o&&n.Validator.validateBuiltInConverterFallback(i,r);let s=this.envService.get(e,void 0);if(s===void 0)return a?i===`time`&&typeof r==`string`?t.BuiltInConverters.getConverter(i)(``,r):r:null;let c=t.BuiltInConverters.getConverter(i)(s,r);return c===void 0&&!a?null:c}processArrayConverter(r,i,a,o){if(n.Validator.arrayConverter(a),o&&i!==void 0&&!Array.isArray(i))throw new e.EnvaptError(101,`ArrayOf<...> requires that the fallback be an array, got ${typeof i}`);o&&Array.isArray(i)&&(n.Validator.validateArrayFallbackElementTypes(i),n.Validator.validateArrayConverterElementTypeMatch(a.of,i));let s=this.envService.get(r,void 0);if(s===void 0){if(!o)return null;if(a.of===`time`&&Array.isArray(i)&&i.every(e=>typeof e==`string`)){let e=t.BuiltInConverters.getConverter(`time`);return i.map(t=>e(``,t))}return i}return t.BuiltInConverters.processArrayConverter(s,a,this.envService.isStrict())}processCustomConverter(e,t,r,i){return n.Validator.customConvertor(r),r(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,i,a){let o=this.envService.get(t,void 0);if(o===void 0){if(a)return i;throw new e.EnvaptError(305,`Required environment variable "${r(t)}" is missing or empty.`)}let s;try{s=n[`~standard`].validate(o)}catch(n){throw new e.EnvaptError(209,`Schema for "${r(t)}" threw during validation: ${n.message}`,{cause:n})}if(s instanceof Promise)throw new e.EnvaptError(302,`Schema for "${r(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 "${r(t)}": ${n}`,{issues:s.issues})}return s.value}};exports.ValueConverter=i;
+//# sourceMappingURL=ValueConverter.cjs.map

package/dist/converters/ValueConverter.cjs.map

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

package/dist/converters/ValueConverter.d.cts

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

package/dist/converters/ValueConverter.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ValueConverter.d.cts","names":[],"sources":["../../src/converters/ValueConverter.ts"],"mappings":";;;;;;;AAkBA;;;cAAa,cAAA;EAAA,iBACoB,UAAA;cAAA,UAAA,EAAY,eAAA;EAEzC,YAAA,WAAA,CACI,GAAA,EAAK,WAAA,EACL,QAAA,EAAU,SAAA,cACV,SAAA,EAAW,eAAA,CAAgB,SAAA,eAC3B,WAAA,YACD,SAAA;EAAA,QAoBK,2BAAA;EAAA,QAUA,wBAAA;EAAA,QAYA,uBAAA;EAAA,QAmCA,qBAAA;EAAA,QA0CA,sBAAA;EAAA,QAaA,gBAAA;EAgBR,iBAAA,CAAkB,GAAA,EAAK,WAAA,EAAa,MAAA,EAAQ,gBAAA,EAAkB,QAAA,WAAmB,WAAA;AAAA"}

package/dist/converters/ValueConverter.d.mts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"ValueConverter.d.mts","names":[],"sources":["../../src/converters/ValueConverter.ts"],"mappings":";;;;;;;AAkBA;;;cAAa,cAAA;EAAA,iBACoB,UAAA;cAAA,UAAA,EAAY,eAAA;EAEzC,YAAA,WAAA,CACI,GAAA,EAAK,WAAA,EACL,QAAA,EAAU,SAAA,cACV,SAAA,EAAW,eAAA,CAAgB,SAAA,eAC3B,WAAA,YACD,SAAA;EAAA,QAoBK,2BAAA;EAAA,QAUA,wBAAA;EAAA,QAYA,uBAAA;EAAA,QAmCA,qBAAA;EAAA,QA0CA,sBAAA;EAAA,QAaA,gBAAA;EAgBR,iBAAA,CAAkB,GAAA,EAAK,WAAA,EAAa,MAAA,EAAQ,gBAAA,EAAkB,QAAA,WAAmB,WAAA;AAAA"}

package/dist/converters/ValueConverter.mjs

@@ -0,0 +1,2 @@
+import{EnvaptError as e}from"../Error.mjs";import{BuiltInConverters as t}from"./BuiltInConverters.mjs";import{Validator as n}from"../Validators.mjs";function r(e){return Array.isArray(e)?`[${e.join(`, `)}]`:String(e)}var i=class{envService;constructor(e){this.envService=e}convertValue(e,t,r,i){let a=this.resolveConverter(r,t),o=this.processFallbackForConverter(a,t);if(n.isArrayConverter(a))return this.processArrayConverter(e,o,a,i);if(n.isPrimitiveConstructor(a)){let t=this.convertPrimitiveToString(a);return this.processBuiltInConverter(e,o,t,i,!0)}return n.isBuiltInConverter(a)?this.processBuiltInConverter(e,o,a,i,!1):this.processCustomConverter(e,o,a,i)}processFallbackForConverter(e,t){return n.isPrimitiveConstructor(e)&&t!==void 0?n.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,r,i,a,o){n.builtInConverter(i),a&&r!==void 0&&!o&&n.validateBuiltInConverterFallback(i,r);let s=this.envService.get(e,void 0);if(s===void 0)return a?i===`time`&&typeof r==`string`?t.getConverter(i)(``,r):r:null;let c=t.getConverter(i)(s,r);return c===void 0&&!a?null:c}processArrayConverter(r,i,a,o){if(n.arrayConverter(a),o&&i!==void 0&&!Array.isArray(i))throw new e(101,`ArrayOf<...> requires that the fallback be an array, got ${typeof i}`);o&&Array.isArray(i)&&(n.validateArrayFallbackElementTypes(i),n.validateArrayConverterElementTypeMatch(a.of,i));let s=this.envService.get(r,void 0);if(s===void 0){if(!o)return null;if(a.of===`time`&&Array.isArray(i)&&i.every(e=>typeof e==`string`)){let e=t.getConverter(`time`);return i.map(t=>e(``,t))}return i}return t.processArrayConverter(s,a,this.envService.isStrict())}processCustomConverter(e,t,r,i){return n.customConvertor(r),r(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,i,a){let o=this.envService.get(t,void 0);if(o===void 0){if(a)return i;throw new e(305,`Required environment variable "${r(t)}" is missing or empty.`)}let s;try{s=n[`~standard`].validate(o)}catch(n){throw new e(209,`Schema for "${r(t)}" threw during validation: ${n.message}`,{cause:n})}if(s instanceof Promise)throw new e(302,`Schema for "${r(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 "${r(t)}": ${n}`,{issues:s.issues})}return s.value}};export{i as ValueConverter};
+//# sourceMappingURL=ValueConverter.mjs.map

package/dist/converters/ValueConverter.mjs.map

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

package/dist/core/AdvancedMethods.cjs

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

package/dist/core/AdvancedMethods.cjs.map

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

package/dist/core/AdvancedMethods.d.cts

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

package/dist/core/AdvancedMethods.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AdvancedMethods.d.cts","names":[],"sources":["../../src/core/AdvancedMethods.ts"],"mappings":";;;;;;;;UAgBU,uBAAA;EACN,SAAA,EAAW,UAAU;EACrB,QAAA;AAAA;AAAA,UAGM,sBAAA;EACN,SAAA,EAAW,iBAAiB,CAAC,WAAA;EAC7B,QAAA;AAAA;;;;;cAiBS,eAAA,SAAwB,gBAAA;EAtBzB;AAAA;;;;;;EAAA,OAgCD,QAAA,mBAA2B,YAAA,yBAAA,CAC9B,GAAA,EAAK,WAAA,EACL,SAAA,UACA,QAAA,GAAW,SAAA,GACZ,iBAAA,SAA0B,SAAA;EAAA,OACtB,QAAA,oBAA4B,gBAAA,GAAmB,OAAA,wBAAA,CAClD,GAAA,EAAK,WAAA,EACL,SAAA,EAAW,UAAA,EACX,QAAA,GAAW,SAAA,GACZ,uBAAA,CAAwB,UAAA,EAAY,SAAA;EAAA,OAChC,QAAA,SAAA,CAAkB,GAAA,EAAK,WAAA,EAAa,SAAA,EAAW,gBAAA,GAAmB,OAAA,EAAS,QAAA,GAAW,OAAA,GAAU,OAAA;EAAA,OAChG,QAAA,CAAS,GAAA,EAAK,WAAA,EAAa,OAAA,EAAS,uBAAA;EAAA,OACpC,QAAA,oBAA4B,gBAAA,GAAmB,OAAA,CAAA,CAClD,GAAA,EAAK,WAAA,EACL,OAAA,EAAS,uBAAA,CAAwB,UAAA,IAClC,wBAAA,CAAyB,UAAA;EAzBnB;;;EAsET,QAAA,mBAA2B,YAAA,yBAAA,CACvB,GAAA,EAAK,WAAA,EACL,SAAA,UACA,QAAA,GAAW,SAAA,GACZ,iBAAA,SAA0B,SAAA;EAC7B,QAAA,oBAA4B,gBAAA,GAAmB,OAAA,wBAAA,CAC3C,GAAA,EAAK,WAAA,EACL,SAAA,EAAW,UAAA,EACX,QAAA,GAAW,SAAA,GACZ,uBAAA,CAAwB,UAAA,EAAY,SAAA;EACvC,QAAA,SAAA,CAAkB,GAAA,EAAK,WAAA,EAAa,SAAA,EAAW,gBAAA,GAAmB,OAAA,EAAS,QAAA,GAAW,OAAA,GAAU,OAAA;EAChG,QAAA,CAAS,GAAA,EAAK,WAAA,EAAa,OAAA,EAAS,uBAAA;EACpC,QAAA,oBAA4B,gBAAA,GAAmB,OAAA,CAAA,CAC3C,GAAA,EAAK,WAAA,EACL,OAAA,EAAS,uBAAA,CAAwB,UAAA,IAClC,wBAAA,CAAyB,UAAA;EAtEO;;;;EAAA,OAsF5B,OAAA,gCAAuC,WAAA,yBAAA,CAC1C,GAAA,EAAK,WAAA,EACL,SAAA,EAAW,iBAAA,CAAkB,WAAA,GAC7B,QAAA,GAAW,SAAA,GACZ,iBAAA,CAAkB,WAAA,EAAa,SAAA;EAAA,OAC3B,OAAA,aAAA,CAAqB,GAAA,EAAK,WAAA,EAAa,OAAA,EAAS,sBAAA,CAAuB,WAAA,IAAe,WAAA;EAvFtD;;;EAoIvC,OAAA,gCAAuC,WAAA,yBAAA,CACnC,GAAA,EAAK,WAAA,EACL,SAAA,EAAW,iBAAA,CAAkB,WAAA,GAC7B,QAAA,GAAW,SAAA,GACZ,iBAAA,CAAkB,WAAA,EAAa,SAAA;EAClC,OAAA,aAAA,CAAqB,GAAA,EAAK,WAAA,EAAa,OAAA,EAAS,sBAAA,CAAuB,WAAA,IAAe,WAAA;EAxIO;;;;;;;;;;;;;;;EAAA,OAgKtF,KAAA,gBAAqB,gBAAA,CAAA,CACxB,GAAA,EAAK,WAAA,EACL,MAAA,EAAQ,gBAAA,CAAiB,MAAA,GACzB,QAAA,GAAW,iBAAA,CAAkB,MAAA,IAC9B,iBAAA,CAAkB,MAAA;EA7GO;;;EA6H5B,KAAA,gBAAqB,gBAAA,CAAA,CACjB,GAAA,EAAK,WAAA,EACL,MAAA,EAAQ,gBAAA,CAAiB,MAAA,GACzB,QAAA,GAAW,iBAAA,CAAkB,MAAA,IAC9B,iBAAA,CAAkB,MAAA;AAAA"}

package/dist/core/AdvancedMethods.d.mts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"AdvancedMethods.d.mts","names":[],"sources":["../../src/core/AdvancedMethods.ts"],"mappings":";;;;;;;;UAgBU,uBAAA;EACN,SAAA,EAAW,UAAU;EACrB,QAAA;AAAA;AAAA,UAGM,sBAAA;EACN,SAAA,EAAW,iBAAiB,CAAC,WAAA;EAC7B,QAAA;AAAA;;;;;cAiBS,eAAA,SAAwB,gBAAA;EAtBzB;AAAA;;;;;;EAAA,OAgCD,QAAA,mBAA2B,YAAA,yBAAA,CAC9B,GAAA,EAAK,WAAA,EACL,SAAA,UACA,QAAA,GAAW,SAAA,GACZ,iBAAA,SAA0B,SAAA;EAAA,OACtB,QAAA,oBAA4B,gBAAA,GAAmB,OAAA,wBAAA,CAClD,GAAA,EAAK,WAAA,EACL,SAAA,EAAW,UAAA,EACX,QAAA,GAAW,SAAA,GACZ,uBAAA,CAAwB,UAAA,EAAY,SAAA;EAAA,OAChC,QAAA,SAAA,CAAkB,GAAA,EAAK,WAAA,EAAa,SAAA,EAAW,gBAAA,GAAmB,OAAA,EAAS,QAAA,GAAW,OAAA,GAAU,OAAA;EAAA,OAChG,QAAA,CAAS,GAAA,EAAK,WAAA,EAAa,OAAA,EAAS,uBAAA;EAAA,OACpC,QAAA,oBAA4B,gBAAA,GAAmB,OAAA,CAAA,CAClD,GAAA,EAAK,WAAA,EACL,OAAA,EAAS,uBAAA,CAAwB,UAAA,IAClC,wBAAA,CAAyB,UAAA;EAzBnB;;;EAsET,QAAA,mBAA2B,YAAA,yBAAA,CACvB,GAAA,EAAK,WAAA,EACL,SAAA,UACA,QAAA,GAAW,SAAA,GACZ,iBAAA,SAA0B,SAAA;EAC7B,QAAA,oBAA4B,gBAAA,GAAmB,OAAA,wBAAA,CAC3C,GAAA,EAAK,WAAA,EACL,SAAA,EAAW,UAAA,EACX,QAAA,GAAW,SAAA,GACZ,uBAAA,CAAwB,UAAA,EAAY,SAAA;EACvC,QAAA,SAAA,CAAkB,GAAA,EAAK,WAAA,EAAa,SAAA,EAAW,gBAAA,GAAmB,OAAA,EAAS,QAAA,GAAW,OAAA,GAAU,OAAA;EAChG,QAAA,CAAS,GAAA,EAAK,WAAA,EAAa,OAAA,EAAS,uBAAA;EACpC,QAAA,oBAA4B,gBAAA,GAAmB,OAAA,CAAA,CAC3C,GAAA,EAAK,WAAA,EACL,OAAA,EAAS,uBAAA,CAAwB,UAAA,IAClC,wBAAA,CAAyB,UAAA;EAtEO;;;;EAAA,OAsF5B,OAAA,gCAAuC,WAAA,yBAAA,CAC1C,GAAA,EAAK,WAAA,EACL,SAAA,EAAW,iBAAA,CAAkB,WAAA,GAC7B,QAAA,GAAW,SAAA,GACZ,iBAAA,CAAkB,WAAA,EAAa,SAAA;EAAA,OAC3B,OAAA,aAAA,CAAqB,GAAA,EAAK,WAAA,EAAa,OAAA,EAAS,sBAAA,CAAuB,WAAA,IAAe,WAAA;EAvFtD;;;EAoIvC,OAAA,gCAAuC,WAAA,yBAAA,CACnC,GAAA,EAAK,WAAA,EACL,SAAA,EAAW,iBAAA,CAAkB,WAAA,GAC7B,QAAA,GAAW,SAAA,GACZ,iBAAA,CAAkB,WAAA,EAAa,SAAA;EAClC,OAAA,aAAA,CAAqB,GAAA,EAAK,WAAA,EAAa,OAAA,EAAS,sBAAA,CAAuB,WAAA,IAAe,WAAA;EAxIO;;;;;;;;;;;;;;;EAAA,OAgKtF,KAAA,gBAAqB,gBAAA,CAAA,CACxB,GAAA,EAAK,WAAA,EACL,MAAA,EAAQ,gBAAA,CAAiB,MAAA,GACzB,QAAA,GAAW,iBAAA,CAAkB,MAAA,IAC9B,iBAAA,CAAkB,MAAA;EA7GO;;;EA6H5B,KAAA,gBAAqB,gBAAA,CAAA,CACjB,GAAA,EAAK,WAAA,EACL,MAAA,EAAQ,gBAAA,CAAiB,MAAA,GACzB,QAAA,GAAW,iBAAA,CAAkB,MAAA,IAC9B,iBAAA,CAAkB,MAAA;AAAA"}

package/dist/core/AdvancedMethods.mjs

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

package/dist/core/AdvancedMethods.mjs.map

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

package/dist/core/EnvapterBase.cjs

@@ -0,0 +1,2 @@
+const e=require("../_virtual/_rolldown/runtime.cjs"),t=require("../Error.cjs"),n=require("../Validators.cjs"),r=require("../Debug.cjs"),i=require("../Dotenv.cjs");let a=require("node:path"),o=require("node:process");o=e.__toESM(o,1);let s=require("node:url");const c=new Map;var l=class e{static _envPaths=[`.env`];static _envPathsExplicitlySet=!1;static _baseDir=void 0;static _userDefinedEnvFileOptions={};static _strict=!1;static _syncProcessEnv=!1;static _dotenvAddedKeys=new Set;static set strict(t){e._strict=t,this.refreshCache()}static get strict(){return e._strict}static set debug(e){r.setDebugLevel(e)}static get debug(){return r.getDebugLevel()}static set syncProcessEnv(t){n.Validator.validateSyncProcessEnv(t);let r=e._syncProcessEnv;e._syncProcessEnv=t,!r&&t&&c.size>0&&this.mirrorToProcessEnv()}static get syncProcessEnv(){return e._syncProcessEnv}static treatAsMissing(t){return!!(t===void 0||t===``||e._strict&&t.trim()===``)}static set envPaths(e){let t=Array.isArray(e)?e:[e];n.Validator.validateEnvFilesExist(t.map(e=>this.resolveAgainstBase(e))),this._envPaths=t,this._envPathsExplicitlySet=!0,this.refreshCache()}static get envPaths(){return this._envPaths}static set baseDir(t){e._baseDir=t===void 0?void 0:this.normalizeBaseDir(t),this.refreshCache()}static get baseDir(){return e._baseDir}static normalizeBaseDir(e){return e instanceof URL||e.startsWith(`file:`)?(0,a.dirname)((0,s.fileURLToPath)(e)):(0,a.resolve)(e)}static resolveAgainstBase(t){return e._baseDir===void 0||(0,a.isAbsolute)(t)?t:(0,a.join)(e._baseDir,t)}static set envFileOptions(e){n.Validator.validateEnvFileOptions(e),this._userDefinedEnvFileOptions=e,this.refreshCache()}static get envFileOptions(){return this._userDefinedEnvFileOptions}static refreshCache(){c.clear(),e._dotenvAddedKeys=new Set,r.debugVerbose(`cache cleared, reloading config`),this.config}static mirrorToProcessEnv(){if(e._dotenvAddedKeys.size!==0){for(let t of e._dotenvAddedKeys){let e=c.get(t);typeof e==`string`&&(o.default.env[t]=e,r.debugVerbose(`mirrored ${t} to process.env`))}r.debugVerbose(`mirrored ${e._dotenvAddedKeys.size} keys to process.env`)}}static resolveEffectivePaths(){return this._envPaths.map(e=>this.resolveAgainstBase(e))}static resolveKeyInput(e){let n=Array.isArray(e)?e:[e];if(n.length===0)throw new t.EnvaptError(304,`At least one environment key must be provided.`);if(n.some(e=>typeof e!=`string`))throw new t.EnvaptError(304,`Environment keys must be strings.`);if(n.some(e=>e.trim()===``))throw new t.EnvaptError(304,`Environment keys cannot be empty strings.`);for(let e of n){let t=this.config.get(e);if(t!==void 0)return{key:e,value:t}}return{key:n[0],value:void 0}}static get config(){if(c.size===0){let t={...o.default.env},n=this.resolveEffectivePaths();r.debugVerbose(`effective .env paths: ${n.length===0?`(none)`:n.join(`, `)}`);let a=new Set;try{a=i.loadDotenv({...this._userDefinedEnvFileOptions,path:n,processEnv:t})}catch{}e._dotenvAddedKeys=a;for(let[e,n]of Object.entries(t))c.set(e,n);r.debugVerbose(`cache populated: ${c.size} keys total`),e._syncProcessEnv&&this.mirrorToProcessEnv()}return c}static load(){this.config}getRaw(t){return e.resolveKeyInput(t).value}};exports.EnvaptCache=c,exports.EnvapterBase=l;
+//# sourceMappingURL=EnvapterBase.cjs.map

package/dist/core/EnvapterBase.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnvapterBase.cjs","names":["getDebugLevel","EnvaptError","process","loadDotenv"],"sources":["../../src/core/EnvapterBase.ts"],"sourcesContent":["import { dirname, isAbsolute, join, resolve } from 'node:path';\nimport process from 'node:process';\nimport { fileURLToPath } from 'node:url';\n\nimport { debugVerbose, getDebugLevel, setDebugLevel } from '../Debug';\nimport { loadDotenv } from '../Dotenv';\nimport { EnvaptError, EnvaptErrorCodes } from '../Error';\nimport { Validator } from '../Validators';\n\nimport type { DebugLevel } from '../Debug';\nimport type { EnvFileOptions } from '../Dotenv';\nimport type { EnvKeyInput } from '../types';\n\n/**\n * Base cache for environment variables and computed values\n * @internal\n */\nexport const EnvaptCache = new Map<string, unknown>();\n\n/**\n * Base class for environment variable management\n * Handles configuration, caching, and basic environment loading\n * @internal\n */\nexport abstract class EnvapterBase {\n    protected static _envPaths: string[] = ['.env'];\n    protected static _envPathsExplicitlySet = false;\n    protected static _baseDir: string | undefined = undefined;\n    protected static _userDefinedEnvFileOptions: EnvFileOptions = {};\n    protected static _strict = false;\n    protected static _syncProcessEnv = false;\n    // Loader-written keys only (collisions skipped). Refilled on every cache rebuild.\n    protected static _dotenvAddedKeys: Set<string> = new Set<string>();\n\n    /**\n     * Enable or disable strict mode. Default `false`. Setting refreshes the cache so\n     * previously-cached converted values get re-evaluated under the new rule.\n     */\n    static set strict(value: boolean) {\n        // Anchored to EnvapterBase: `this._strict` would write an own-property on the subclass that base readers miss.\n        EnvapterBase._strict = value;\n        // `this`, not EnvapterBase: rebuild via the subclass so its `resolveEffectivePaths` override is honored.\n        this.refreshCache();\n    }\n\n    static get strict(): boolean {\n        return EnvapterBase._strict;\n    }\n\n    /**\n     * Set the debug log level. Defaults to `silent`. When unset, reads `ENVAPT_DEBUG` from\n     * `process.env` on first access; the setter overrides any env-var value. Output goes\n     * to stderr prefixed with `[envapt]`.\n     */\n    static set debug(level: DebugLevel) {\n        setDebugLevel(level);\n    }\n\n    static get debug(): DebugLevel {\n        return getDebugLevel();\n    }\n\n    /**\n     * Opt-in mirror of dotenv-loaded keys back to `process.env`. Default `false`.\n     *\n     * Only keys the loader actually wrote are mirrored, so collision behavior follows\n     * `envFileOptions.override`: with the default `false`, pre-existing `process.env` values\n     * are preserved; with `true`, the file value wins in both the cache and the mirror.\n     *\n     * Flipping `false → true` mirrors the existing tracked delta immediately (no cache\n     * refresh). Flipping `true → false` is one-way: previously mirrored keys remain in\n     * `process.env` until the process exits.\n     */\n    static set syncProcessEnv(value: boolean) {\n        Validator.validateSyncProcessEnv(value);\n        const previous = EnvapterBase._syncProcessEnv;\n        // Anchored to EnvapterBase: `this._syncProcessEnv` would write an own-property on the subclass that base readers miss.\n        EnvapterBase._syncProcessEnv = value;\n        if (!previous && value && EnvaptCache.size > 0) this.mirrorToProcessEnv();\n    }\n\n    static get syncProcessEnv(): boolean {\n        return EnvapterBase._syncProcessEnv;\n    }\n\n    protected static treatAsMissing(value: string | undefined): boolean {\n        if (value === undefined || value === '') return true;\n        if (EnvapterBase._strict && value.trim() === '') return true;\n        return false;\n    }\n\n    /**\n     * Set custom .env file paths. Accepts either a single path or array of paths.\n     * Setting new paths clears the cache and reloads environment variables.\n     *\n     * When set, this takes absolute precedence. The dotenv-flow auto-cascade and any\n     * {@link configureProfiles} configuration are ignored.\n     */\n    static set envPaths(paths: string[] | string) {\n        const newPaths = Array.isArray(paths) ? paths : [paths];\n        Validator.validateEnvFilesExist(newPaths.map((p) => this.resolveAgainstBase(p)));\n\n        this._envPaths = newPaths;\n        this._envPathsExplicitlySet = true;\n        this.refreshCache();\n    }\n\n    /**\n     * Get currently configured .env file paths\n     */\n    static get envPaths(): string[] {\n        return this._envPaths;\n    }\n\n    /**\n     * Set a base directory that relative `.env` paths resolve against instead of\n     * `process.cwd()`: the auto-cascade, {@link configureProfiles} paths, and relative\n     * `envPaths`. Absolute paths always bypass it. Pass a directory, or a module URL\n     * (`import.meta.url`, ESM) / `import.meta.dirname` / `__dirname` (CJS) to anchor\n     * resolution next to the calling file regardless of launch directory.\n     *\n     * Set this before `envPaths` so relative `envPaths` validate against the right directory.\n     * Unset (`undefined`) restores `process.cwd()` resolution.\n     */\n    static set baseDir(value: string | URL | undefined) {\n        EnvapterBase._baseDir = value === undefined ? undefined : this.normalizeBaseDir(value);\n        this.refreshCache();\n    }\n\n    static get baseDir(): string | undefined {\n        return EnvapterBase._baseDir;\n    }\n\n    // `file:` URLs resolve to their containing directory; plain paths (`import.meta.dirname`, `__dirname`) are taken as the directory.\n    private static normalizeBaseDir(value: string | URL): string {\n        if (value instanceof URL) return dirname(fileURLToPath(value));\n        if (value.startsWith('file:')) return dirname(fileURLToPath(value));\n        return resolve(value);\n    }\n\n    // No baseDir: path is returned unchanged so Node resolves it against process.cwd() (the historical default).\n    protected static resolveAgainstBase(candidate: string): string {\n        if (EnvapterBase._baseDir === undefined) return candidate;\n        if (isAbsolute(candidate)) return candidate;\n        return join(EnvapterBase._baseDir, candidate);\n    }\n\n    static set envFileOptions(config: EnvFileOptions) {\n        Validator.validateEnvFileOptions(config);\n        this._userDefinedEnvFileOptions = config;\n        this.refreshCache();\n    }\n\n    /**\n     * Get current dotenv configuration options\n     */\n    static get envFileOptions(): EnvFileOptions {\n        return this._userDefinedEnvFileOptions;\n    }\n\n    protected static refreshCache(): void {\n        EnvaptCache.clear();\n        EnvapterBase._dotenvAddedKeys = new Set();\n        debugVerbose('cache cleared, reloading config');\n        void this.config; // getter rebuilds the cache as a side effect\n    }\n\n    protected static mirrorToProcessEnv(): void {\n        if (EnvapterBase._dotenvAddedKeys.size === 0) return;\n        for (const key of EnvapterBase._dotenvAddedKeys) {\n            const value = EnvaptCache.get(key);\n            /* v8 ignore next -- @preserve loader only writes strings; defensive against future cache contents */\n            if (typeof value !== 'string') continue;\n            process.env[key] = value;\n            debugVerbose(`mirrored ${key} to process.env`);\n        }\n        debugVerbose(`mirrored ${EnvapterBase._dotenvAddedKeys.size} keys to process.env`);\n    }\n\n    /**\n     * Resolve the effective `.env` paths to load. Default implementation just returns the\n     * explicit `_envPaths` array; subclasses (`EnvironmentMethods`) override to layer in the\n     * dotenv-flow cascade and any {@link configureProfiles} overrides when `envPaths` was\n     * never explicitly set.\n     * @internal\n     */\n    protected static resolveEffectivePaths(): string[] {\n        /* v8 ignore next -- @preserve */\n        return this._envPaths.map((p) => this.resolveAgainstBase(p));\n    }\n\n    protected static resolveKeyInput(keyInput: EnvKeyInput): { key: string; value: string | undefined } {\n        const keys = Array.isArray(keyInput) ? keyInput : [keyInput];\n        const normalizedKeys = keys as readonly string[];\n\n        if (normalizedKeys.length === 0) {\n            throw new EnvaptError(EnvaptErrorCodes.InvalidKeyInput, 'At least one environment key must be provided.');\n        }\n\n        if (normalizedKeys.some((k) => typeof k !== 'string')) {\n            throw new EnvaptError(EnvaptErrorCodes.InvalidKeyInput, 'Environment keys must be strings.');\n        }\n\n        if (normalizedKeys.some((k) => k.trim() === '')) {\n            throw new EnvaptError(EnvaptErrorCodes.InvalidKeyInput, 'Environment keys cannot be empty strings.');\n        }\n\n        for (const candidate of normalizedKeys) {\n            const value = this.config.get(candidate) as string | undefined;\n            if (value !== undefined) {\n                return { key: candidate, value };\n            }\n        }\n\n        return { key: normalizedKeys[0] as string, value: undefined };\n    }\n\n    protected static get config(): Map<string, unknown> {\n        if (EnvaptCache.size === 0) {\n            // Clone so the loader and downstream reads never mutate process.env.\n            const isolatedEnv: Record<string, string> = { ...(process.env as Record<string, string>) };\n\n            // Outside the try below so a missing configured profile path surfaces its EnvaptError; only dotenv parse errors stay caught.\n            const effectivePaths = this.resolveEffectivePaths();\n            debugVerbose(`effective .env paths: ${effectivePaths.length === 0 ? '(none)' : effectivePaths.join(', ')}`);\n\n            let added = new Set<string>();\n            try {\n                added = loadDotenv({\n                    ...this._userDefinedEnvFileOptions,\n                    path: effectivePaths,\n                    processEnv: isolatedEnv\n                });\n            } catch {}\n            EnvapterBase._dotenvAddedKeys = added;\n            for (const [key, value] of Object.entries(isolatedEnv)) EnvaptCache.set(key, value);\n            debugVerbose(`cache populated: ${EnvaptCache.size} keys total`);\n            if (EnvapterBase._syncProcessEnv) this.mirrorToProcessEnv();\n        }\n\n        return EnvaptCache;\n    }\n\n    /**\n     * Eagerly load the `.env` cascade now instead of lazily on the first read. Idempotent: a no-op\n     * once the cache is built. Useful before mirroring to `process.env` (see {@link syncProcessEnv}),\n     * which is what the `envapt/config` side-effect entry does.\n     */\n    static load(): void {\n        void this.config;\n    }\n\n    /**\n     * Read an environment variable as its raw string, skipping parsing and conversion.\n     */\n    getRaw(key: EnvKeyInput): string | undefined {\n        return EnvapterBase.resolveKeyInput(key).value;\n    }\n}\n"],"mappings":"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"}