envapt 8.0.0-next.0 → 8.0.0-next.2

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

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

package/dist/node/core/AdvancedMethods.mjs

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

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

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

package/dist/node/core/EnvapterBase.cjs

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

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

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

package/dist/node/core/EnvapterBase.mjs

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

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

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

package/dist/node/core/Environment.cjs

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

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

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

package/dist/node/core/Environment.mjs

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

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

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

package/dist/node/core/EnvironmentMethods.cjs

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

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

@@ -1 +1 @@
-{"version":3,"file":"EnvironmentMethods.cjs","names":["EnvapterBase","state"],"sources":["../../../src/core/EnvironmentMethods.ts"],"sourcesContent":["import { determineEnvironment } from './engine';\nimport { EnvapterBase } from './EnvapterBase';\nimport { Environment } from './Environment';\nimport { state } from './state';\n\n/**\n * Mixin for environment detection and checking methods\n * @internal\n */\nexport class EnvironmentMethods extends EnvapterBase {\n    /**\n     * Get the current application environment\n     */\n    static get environment(): Environment {\n        if (state.environment === undefined) {\n            determineEnvironment();\n        }\n        return state.environment as Environment;\n    }\n\n    /**\n     * Set the application environment. Accepts either Environment enum or string value.\n     */\n    static set environment(env: string | Environment) {\n        determineEnvironment(env);\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.environment}\n     */\n    get environment(): Environment {\n        return EnvironmentMethods.environment;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.environment}\n     */\n    set environment(env: string | Environment) {\n        determineEnvironment(env);\n    }\n\n    /**\n     * Check if the current environment is production\n     */\n    static get isProduction(): boolean {\n        return this.environment === Environment.Production;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.isProduction}\n     */\n    get isProduction(): boolean {\n        return EnvironmentMethods.environment === Environment.Production;\n    }\n\n    /**\n     * Check if the current environment is staging\n     */\n    static get isStaging(): boolean {\n        return this.environment === Environment.Staging;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.isStaging}\n     */\n    get isStaging(): boolean {\n        return EnvironmentMethods.environment === Environment.Staging;\n    }\n\n    /**\n     * Check if the current environment is development\n     */\n    static get isDevelopment(): boolean {\n        return this.environment === Environment.Development;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.isDevelopment}\n     */\n    get isDevelopment(): boolean {\n        return EnvironmentMethods.environment === Environment.Development;\n    }\n\n    /**\n     * Check if the current environment is test\n     */\n    static get isTest(): boolean {\n        return this.environment === Environment.Test;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.isTest}\n     */\n    get isTest(): boolean {\n        return EnvironmentMethods.environment === Environment.Test;\n    }\n}\n"],"mappings":"sHASA,IAAa,EAAb,MAAa,UAA2BA,EAAAA,YAAa,CAIjD,WAAW,aAA2B,CAIlC,OAHIC,EAAAA,MAAM,cAAgB,IAAA,IACtB,EAAA,qBAAqB,EAElBA,EAAAA,MAAM,WACjB,CAKA,WAAW,YAAY,EAA2B,CAC9C,EAAA,qBAAqB,CAAG,CAC5B,CAKA,IAAI,aAA2B,CAC3B,OAAO,EAAmB,WAC9B,CAKA,IAAI,YAAY,EAA2B,CACvC,EAAA,qBAAqB,CAAG,CAC5B,CAKA,WAAW,cAAwB,CAC/B,OAAO,KAAK,cAAA,CAChB,CAKA,IAAI,cAAwB,CACxB,OAAO,EAAmB,cAAA,CAC9B,CAKA,WAAW,WAAqB,CAC5B,OAAO,KAAK,cAAA,CAChB,CAKA,IAAI,WAAqB,CACrB,OAAO,EAAmB,cAAA,CAC9B,CAKA,WAAW,eAAyB,CAChC,OAAO,KAAK,cAAA,CAChB,CAKA,IAAI,eAAyB,CACzB,OAAO,EAAmB,cAAA,CAC9B,CAKA,WAAW,QAAkB,CACzB,OAAO,KAAK,cAAA,CAChB,CAKA,IAAI,QAAkB,CAClB,OAAO,EAAmB,cAAA,CAC9B,CACJ"}
+{"version":3,"file":"EnvironmentMethods.cjs","names":["EnvapterBase","state"],"sources":["../../../src/core/EnvironmentMethods.ts"],"sourcesContent":["import { determineEnvironment } from './engine';\nimport { EnvapterBase } from './EnvapterBase';\nimport { Environment } from './Environment';\nimport { state } from './state';\n\n/**\n * Mixin for environment detection and checking methods\n * @internal\n */\nexport class EnvironmentMethods extends EnvapterBase {\n    /**\n     * Get the current application environment\n     * @see {@link https://envapt.materwelon.dev/docs/environment#detecting-the-environment}\n     */\n    static get environment(): Environment {\n        if (state.environment === undefined) {\n            determineEnvironment();\n        }\n        return state.environment as Environment;\n    }\n\n    /**\n     * Set the application environment. Accepts either Environment enum or string value.\n     * @see {@link https://envapt.materwelon.dev/docs/environment#detecting-the-environment}\n     */\n    static set environment(env: string | Environment) {\n        determineEnvironment(env);\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.environment}\n     */\n    get environment(): Environment {\n        return EnvironmentMethods.environment;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.environment}\n     */\n    set environment(env: string | Environment) {\n        determineEnvironment(env);\n    }\n\n    /**\n     * Check if the current environment is production\n     * @see {@link https://envapt.materwelon.dev/docs/environment#branching-on-the-environment}\n     */\n    static get isProduction(): boolean {\n        return this.environment === Environment.Production;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.isProduction}\n     */\n    get isProduction(): boolean {\n        return EnvironmentMethods.environment === Environment.Production;\n    }\n\n    /**\n     * Check if the current environment is staging\n     * @see {@link https://envapt.materwelon.dev/docs/environment#branching-on-the-environment}\n     */\n    static get isStaging(): boolean {\n        return this.environment === Environment.Staging;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.isStaging}\n     */\n    get isStaging(): boolean {\n        return EnvironmentMethods.environment === Environment.Staging;\n    }\n\n    /**\n     * Check if the current environment is development\n     * @see {@link https://envapt.materwelon.dev/docs/environment#branching-on-the-environment}\n     */\n    static get isDevelopment(): boolean {\n        return this.environment === Environment.Development;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.isDevelopment}\n     */\n    get isDevelopment(): boolean {\n        return EnvironmentMethods.environment === Environment.Development;\n    }\n\n    /**\n     * Check if the current environment is test\n     * @see {@link https://envapt.materwelon.dev/docs/environment#branching-on-the-environment}\n     */\n    static get isTest(): boolean {\n        return this.environment === Environment.Test;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.isTest}\n     */\n    get isTest(): boolean {\n        return EnvironmentMethods.environment === Environment.Test;\n    }\n}\n"],"mappings":"4HASA,IAAa,EAAb,MAAa,UAA2BA,EAAAA,YAAa,CAKjD,WAAW,aAA2B,CAIlC,OAHIC,EAAAA,MAAM,cAAgB,IAAA,IACtB,EAAA,qBAAqB,EAElBA,EAAAA,MAAM,WACjB,CAMA,WAAW,YAAY,EAA2B,CAC9C,EAAA,qBAAqB,CAAG,CAC5B,CAKA,IAAI,aAA2B,CAC3B,OAAO,EAAmB,WAC9B,CAKA,IAAI,YAAY,EAA2B,CACvC,EAAA,qBAAqB,CAAG,CAC5B,CAMA,WAAW,cAAwB,CAC/B,OAAO,KAAK,cAAA,CAChB,CAKA,IAAI,cAAwB,CACxB,OAAO,EAAmB,cAAA,CAC9B,CAMA,WAAW,WAAqB,CAC5B,OAAO,KAAK,cAAA,CAChB,CAKA,IAAI,WAAqB,CACrB,OAAO,EAAmB,cAAA,CAC9B,CAMA,WAAW,eAAyB,CAChC,OAAO,KAAK,cAAA,CAChB,CAKA,IAAI,eAAyB,CACzB,OAAO,EAAmB,cAAA,CAC9B,CAMA,WAAW,QAAkB,CACzB,OAAO,KAAK,cAAA,CAChB,CAKA,IAAI,QAAkB,CAClB,OAAO,EAAmB,cAAA,CAC9B,CACJ"}

package/dist/node/core/EnvironmentMethods.mjs

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

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

@@ -1 +1 @@
-{"version":3,"file":"EnvironmentMethods.mjs","names":[],"sources":["../../../src/core/EnvironmentMethods.ts"],"sourcesContent":["import { determineEnvironment } from './engine';\nimport { EnvapterBase } from './EnvapterBase';\nimport { Environment } from './Environment';\nimport { state } from './state';\n\n/**\n * Mixin for environment detection and checking methods\n * @internal\n */\nexport class EnvironmentMethods extends EnvapterBase {\n    /**\n     * Get the current application environment\n     */\n    static get environment(): Environment {\n        if (state.environment === undefined) {\n            determineEnvironment();\n        }\n        return state.environment as Environment;\n    }\n\n    /**\n     * Set the application environment. Accepts either Environment enum or string value.\n     */\n    static set environment(env: string | Environment) {\n        determineEnvironment(env);\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.environment}\n     */\n    get environment(): Environment {\n        return EnvironmentMethods.environment;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.environment}\n     */\n    set environment(env: string | Environment) {\n        determineEnvironment(env);\n    }\n\n    /**\n     * Check if the current environment is production\n     */\n    static get isProduction(): boolean {\n        return this.environment === Environment.Production;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.isProduction}\n     */\n    get isProduction(): boolean {\n        return EnvironmentMethods.environment === Environment.Production;\n    }\n\n    /**\n     * Check if the current environment is staging\n     */\n    static get isStaging(): boolean {\n        return this.environment === Environment.Staging;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.isStaging}\n     */\n    get isStaging(): boolean {\n        return EnvironmentMethods.environment === Environment.Staging;\n    }\n\n    /**\n     * Check if the current environment is development\n     */\n    static get isDevelopment(): boolean {\n        return this.environment === Environment.Development;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.isDevelopment}\n     */\n    get isDevelopment(): boolean {\n        return EnvironmentMethods.environment === Environment.Development;\n    }\n\n    /**\n     * Check if the current environment is test\n     */\n    static get isTest(): boolean {\n        return this.environment === Environment.Test;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.isTest}\n     */\n    get isTest(): boolean {\n        return EnvironmentMethods.environment === Environment.Test;\n    }\n}\n"],"mappings":"oKASA,IAAa,EAAb,MAAa,UAA2B,CAAa,CAIjD,WAAW,aAA2B,CAIlC,OAHI,EAAM,cAAgB,IAAA,IACtB,EAAqB,EAElB,EAAM,WACjB,CAKA,WAAW,YAAY,EAA2B,CAC9C,EAAqB,CAAG,CAC5B,CAKA,IAAI,aAA2B,CAC3B,OAAO,EAAmB,WAC9B,CAKA,IAAI,YAAY,EAA2B,CACvC,EAAqB,CAAG,CAC5B,CAKA,WAAW,cAAwB,CAC/B,OAAO,KAAK,cAAA,CAChB,CAKA,IAAI,cAAwB,CACxB,OAAO,EAAmB,cAAA,CAC9B,CAKA,WAAW,WAAqB,CAC5B,OAAO,KAAK,cAAA,CAChB,CAKA,IAAI,WAAqB,CACrB,OAAO,EAAmB,cAAA,CAC9B,CAKA,WAAW,eAAyB,CAChC,OAAO,KAAK,cAAA,CAChB,CAKA,IAAI,eAAyB,CACzB,OAAO,EAAmB,cAAA,CAC9B,CAKA,WAAW,QAAkB,CACzB,OAAO,KAAK,cAAA,CAChB,CAKA,IAAI,QAAkB,CAClB,OAAO,EAAmB,cAAA,CAC9B,CACJ"}
+{"version":3,"file":"EnvironmentMethods.mjs","names":[],"sources":["../../../src/core/EnvironmentMethods.ts"],"sourcesContent":["import { determineEnvironment } from './engine';\nimport { EnvapterBase } from './EnvapterBase';\nimport { Environment } from './Environment';\nimport { state } from './state';\n\n/**\n * Mixin for environment detection and checking methods\n * @internal\n */\nexport class EnvironmentMethods extends EnvapterBase {\n    /**\n     * Get the current application environment\n     * @see {@link https://envapt.materwelon.dev/docs/environment#detecting-the-environment}\n     */\n    static get environment(): Environment {\n        if (state.environment === undefined) {\n            determineEnvironment();\n        }\n        return state.environment as Environment;\n    }\n\n    /**\n     * Set the application environment. Accepts either Environment enum or string value.\n     * @see {@link https://envapt.materwelon.dev/docs/environment#detecting-the-environment}\n     */\n    static set environment(env: string | Environment) {\n        determineEnvironment(env);\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.environment}\n     */\n    get environment(): Environment {\n        return EnvironmentMethods.environment;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.environment}\n     */\n    set environment(env: string | Environment) {\n        determineEnvironment(env);\n    }\n\n    /**\n     * Check if the current environment is production\n     * @see {@link https://envapt.materwelon.dev/docs/environment#branching-on-the-environment}\n     */\n    static get isProduction(): boolean {\n        return this.environment === Environment.Production;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.isProduction}\n     */\n    get isProduction(): boolean {\n        return EnvironmentMethods.environment === Environment.Production;\n    }\n\n    /**\n     * Check if the current environment is staging\n     * @see {@link https://envapt.materwelon.dev/docs/environment#branching-on-the-environment}\n     */\n    static get isStaging(): boolean {\n        return this.environment === Environment.Staging;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.isStaging}\n     */\n    get isStaging(): boolean {\n        return EnvironmentMethods.environment === Environment.Staging;\n    }\n\n    /**\n     * Check if the current environment is development\n     * @see {@link https://envapt.materwelon.dev/docs/environment#branching-on-the-environment}\n     */\n    static get isDevelopment(): boolean {\n        return this.environment === Environment.Development;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.isDevelopment}\n     */\n    get isDevelopment(): boolean {\n        return EnvironmentMethods.environment === Environment.Development;\n    }\n\n    /**\n     * Check if the current environment is test\n     * @see {@link https://envapt.materwelon.dev/docs/environment#branching-on-the-environment}\n     */\n    static get isTest(): boolean {\n        return this.environment === Environment.Test;\n    }\n\n    /**\n     * @see {@link EnvironmentMethods.isTest}\n     */\n    get isTest(): boolean {\n        return EnvironmentMethods.environment === Environment.Test;\n    }\n}\n"],"mappings":"oKASA,IAAa,EAAb,MAAa,UAA2B,CAAa,CAKjD,WAAW,aAA2B,CAIlC,OAHI,EAAM,cAAgB,IAAA,IACtB,EAAqB,EAElB,EAAM,WACjB,CAMA,WAAW,YAAY,EAA2B,CAC9C,EAAqB,CAAG,CAC5B,CAKA,IAAI,aAA2B,CAC3B,OAAO,EAAmB,WAC9B,CAKA,IAAI,YAAY,EAA2B,CACvC,EAAqB,CAAG,CAC5B,CAMA,WAAW,cAAwB,CAC/B,OAAO,KAAK,cAAA,CAChB,CAKA,IAAI,cAAwB,CACxB,OAAO,EAAmB,cAAA,CAC9B,CAMA,WAAW,WAAqB,CAC5B,OAAO,KAAK,cAAA,CAChB,CAKA,IAAI,WAAqB,CACrB,OAAO,EAAmB,cAAA,CAC9B,CAMA,WAAW,eAAyB,CAChC,OAAO,KAAK,cAAA,CAChB,CAKA,IAAI,eAAyB,CACzB,OAAO,EAAmB,cAAA,CAC9B,CAMA,WAAW,QAAkB,CACzB,OAAO,KAAK,cAAA,CAChB,CAKA,IAAI,QAAkB,CAClB,OAAO,EAAmB,cAAA,CAC9B,CACJ"}

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

@@ -1 +1 @@
-{"version":3,"file":"PrimitiveMethods.cjs","names":["EnvironmentMethods","readPrimitive"],"sources":["../../../src/core/PrimitiveMethods.ts"],"sourcesContent":["import { Primitive, readPrimitive } from './engine';\nimport { EnvironmentMethods } from './EnvironmentMethods';\n\nimport type { ConditionalReturn, EnvKeyInput } from '../types';\n\n/**\n * @internal\n */\nexport class PrimitiveMethods extends EnvironmentMethods {\n    /**\n     * Get a string environment variable with optional fallback.\n     * Supports template variable resolution using `${VAR}` syntax.\n     * Accepts a single key or an ordered array of keys (first match wins).\n     */\n    static get<Default extends string | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<string, Default> {\n        return readPrimitive(key, Primitive.String, def);\n    }\n\n    /**\n     * @see {@link PrimitiveMethods.get}\n     */\n    get<Default extends string | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<string, Default> {\n        return readPrimitive(key, Primitive.String, def);\n    }\n\n    /**\n     * Get a number environment variable with optional fallback.\n     * Automatically converts string values to numbers.\n     * Accepts a single key or an ordered array of keys (first match wins).\n     */\n    static getNumber<Default extends number | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<number, Default> {\n        return readPrimitive(key, Primitive.Number, def);\n    }\n\n    /**\n     * @see {@link PrimitiveMethods.getNumber}\n     */\n    getNumber<Default extends number | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<number, Default> {\n        return readPrimitive(key, Primitive.Number, def);\n    }\n\n    /**\n     * Get a boolean environment variable with optional fallback.\n     * Recognizes: `1`, `yes`, `true`, `on` as **true**; `0`, `no`, `false`, `off` as **false** (case-insensitive).\n     * Accepts a single key or an ordered array of keys (first match wins).\n     */\n    static getBoolean<Default extends boolean | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<boolean, Default> {\n        return readPrimitive(key, Primitive.Boolean, def);\n    }\n\n    /**\n     * @see {@link PrimitiveMethods.getBoolean}\n     */\n    getBoolean<Default extends boolean | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<boolean, Default> {\n        return readPrimitive(key, Primitive.Boolean, def);\n    }\n\n    /**\n     * Get a bigint environment variable with optional fallback.\n     * Automatically converts string values to bigint.\n     * Accepts a single key or an ordered array of keys (first match wins).\n     */\n    static getBigInt<Default extends bigint | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<bigint, Default> {\n        return readPrimitive(key, Primitive.BigInt, def);\n    }\n\n    /**\n     * @see {@link PrimitiveMethods.getBigInt}\n     */\n    getBigInt<Default extends bigint | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<bigint, Default> {\n        return readPrimitive(key, Primitive.BigInt, def);\n    }\n\n    /**\n     * Get a symbol environment variable with optional fallback.\n     * Creates a symbol from the string value.\n     * Accepts a single key or an ordered array of keys (first match wins).\n     */\n    static getSymbol<Default extends symbol | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<symbol, Default> {\n        return readPrimitive(key, Primitive.Symbol, def);\n    }\n\n    /**\n     * @see {@link PrimitiveMethods.getSymbol}\n     */\n    getSymbol<Default extends symbol | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<symbol, Default> {\n        return readPrimitive(key, Primitive.Symbol, def);\n    }\n}\n"],"mappings":"sEAQA,IAAa,EAAb,cAAsCA,EAAAA,kBAAmB,CAMrD,OAAO,IACH,EACA,EACkC,CAClC,OAAOC,EAAAA,cAAc,EAAA,EAAuB,CAAG,CACnD,CAKA,IACI,EACA,EACkC,CAClC,OAAOA,EAAAA,cAAc,EAAA,EAAuB,CAAG,CACnD,CAOA,OAAO,UACH,EACA,EACkC,CAClC,OAAOA,EAAAA,cAAc,EAAA,EAAuB,CAAG,CACnD,CAKA,UACI,EACA,EACkC,CAClC,OAAOA,EAAAA,cAAc,EAAA,EAAuB,CAAG,CACnD,CAOA,OAAO,WACH,EACA,EACmC,CACnC,OAAOA,EAAAA,cAAc,EAAA,EAAwB,CAAG,CACpD,CAKA,WACI,EACA,EACmC,CACnC,OAAOA,EAAAA,cAAc,EAAA,EAAwB,CAAG,CACpD,CAOA,OAAO,UACH,EACA,EACkC,CAClC,OAAOA,EAAAA,cAAc,EAAA,EAAuB,CAAG,CACnD,CAKA,UACI,EACA,EACkC,CAClC,OAAOA,EAAAA,cAAc,EAAA,EAAuB,CAAG,CACnD,CAOA,OAAO,UACH,EACA,EACkC,CAClC,OAAOA,EAAAA,cAAc,EAAA,EAAuB,CAAG,CACnD,CAKA,UACI,EACA,EACkC,CAClC,OAAOA,EAAAA,cAAc,EAAA,EAAuB,CAAG,CACnD,CACJ"}
+{"version":3,"file":"PrimitiveMethods.cjs","names":["EnvironmentMethods","readPrimitive"],"sources":["../../../src/core/PrimitiveMethods.ts"],"sourcesContent":["import { Primitive, readPrimitive } from './engine';\nimport { EnvironmentMethods } from './EnvironmentMethods';\n\nimport type { ConditionalReturn, EnvKeyInput } from '../types';\n\n/**\n * @internal\n */\nexport class PrimitiveMethods extends EnvironmentMethods {\n    /**\n     * Get a string environment variable with optional fallback.\n     * Supports template variable resolution using `${VAR}` syntax.\n     * Accepts a single key or an ordered array of keys (first match wins).\n     * @see {@link https://envapt.materwelon.dev/docs/envapter#primitives}\n     */\n    static get<Default extends string | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<string, Default> {\n        return readPrimitive(key, Primitive.String, def);\n    }\n\n    /**\n     * @see {@link PrimitiveMethods.get}\n     */\n    get<Default extends string | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<string, Default> {\n        return readPrimitive(key, Primitive.String, def);\n    }\n\n    /**\n     * Get a number environment variable with optional fallback.\n     * Automatically converts string values to numbers.\n     * Accepts a single key or an ordered array of keys (first match wins).\n     * @see {@link https://envapt.materwelon.dev/docs/envapter#primitives}\n     */\n    static getNumber<Default extends number | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<number, Default> {\n        return readPrimitive(key, Primitive.Number, def);\n    }\n\n    /**\n     * @see {@link PrimitiveMethods.getNumber}\n     */\n    getNumber<Default extends number | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<number, Default> {\n        return readPrimitive(key, Primitive.Number, def);\n    }\n\n    /**\n     * Get a boolean environment variable with optional fallback.\n     * Recognizes: `1`, `yes`, `true`, `on` as **true**; `0`, `no`, `false`, `off` as **false** (case-insensitive).\n     * Accepts a single key or an ordered array of keys (first match wins).\n     * @see {@link https://envapt.materwelon.dev/docs/envapter#primitives}\n     */\n    static getBoolean<Default extends boolean | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<boolean, Default> {\n        return readPrimitive(key, Primitive.Boolean, def);\n    }\n\n    /**\n     * @see {@link PrimitiveMethods.getBoolean}\n     */\n    getBoolean<Default extends boolean | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<boolean, Default> {\n        return readPrimitive(key, Primitive.Boolean, def);\n    }\n\n    /**\n     * Get a bigint environment variable with optional fallback.\n     * Automatically converts string values to bigint.\n     * Accepts a single key or an ordered array of keys (first match wins).\n     * @see {@link https://envapt.materwelon.dev/docs/envapter#primitives}\n     */\n    static getBigInt<Default extends bigint | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<bigint, Default> {\n        return readPrimitive(key, Primitive.BigInt, def);\n    }\n\n    /**\n     * @see {@link PrimitiveMethods.getBigInt}\n     */\n    getBigInt<Default extends bigint | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<bigint, Default> {\n        return readPrimitive(key, Primitive.BigInt, def);\n    }\n\n    /**\n     * Get a symbol environment variable with optional fallback.\n     * Creates a symbol from the string value.\n     * Accepts a single key or an ordered array of keys (first match wins).\n     * @see {@link https://envapt.materwelon.dev/docs/envapter#primitives}\n     */\n    static getSymbol<Default extends symbol | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<symbol, Default> {\n        return readPrimitive(key, Primitive.Symbol, def);\n    }\n\n    /**\n     * @see {@link PrimitiveMethods.getSymbol}\n     */\n    getSymbol<Default extends symbol | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<symbol, Default> {\n        return readPrimitive(key, Primitive.Symbol, def);\n    }\n}\n"],"mappings":"sEAQA,IAAa,EAAb,cAAsCA,EAAAA,kBAAmB,CAOrD,OAAO,IACH,EACA,EACkC,CAClC,OAAOC,EAAAA,cAAc,EAAA,EAAuB,CAAG,CACnD,CAKA,IACI,EACA,EACkC,CAClC,OAAOA,EAAAA,cAAc,EAAA,EAAuB,CAAG,CACnD,CAQA,OAAO,UACH,EACA,EACkC,CAClC,OAAOA,EAAAA,cAAc,EAAA,EAAuB,CAAG,CACnD,CAKA,UACI,EACA,EACkC,CAClC,OAAOA,EAAAA,cAAc,EAAA,EAAuB,CAAG,CACnD,CAQA,OAAO,WACH,EACA,EACmC,CACnC,OAAOA,EAAAA,cAAc,EAAA,EAAwB,CAAG,CACpD,CAKA,WACI,EACA,EACmC,CACnC,OAAOA,EAAAA,cAAc,EAAA,EAAwB,CAAG,CACpD,CAQA,OAAO,UACH,EACA,EACkC,CAClC,OAAOA,EAAAA,cAAc,EAAA,EAAuB,CAAG,CACnD,CAKA,UACI,EACA,EACkC,CAClC,OAAOA,EAAAA,cAAc,EAAA,EAAuB,CAAG,CACnD,CAQA,OAAO,UACH,EACA,EACkC,CAClC,OAAOA,EAAAA,cAAc,EAAA,EAAuB,CAAG,CACnD,CAKA,UACI,EACA,EACkC,CAClC,OAAOA,EAAAA,cAAc,EAAA,EAAuB,CAAG,CACnD,CACJ"}

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

@@ -1 +1 @@
-{"version":3,"file":"PrimitiveMethods.mjs","names":[],"sources":["../../../src/core/PrimitiveMethods.ts"],"sourcesContent":["import { Primitive, readPrimitive } from './engine';\nimport { EnvironmentMethods } from './EnvironmentMethods';\n\nimport type { ConditionalReturn, EnvKeyInput } from '../types';\n\n/**\n * @internal\n */\nexport class PrimitiveMethods extends EnvironmentMethods {\n    /**\n     * Get a string environment variable with optional fallback.\n     * Supports template variable resolution using `${VAR}` syntax.\n     * Accepts a single key or an ordered array of keys (first match wins).\n     */\n    static get<Default extends string | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<string, Default> {\n        return readPrimitive(key, Primitive.String, def);\n    }\n\n    /**\n     * @see {@link PrimitiveMethods.get}\n     */\n    get<Default extends string | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<string, Default> {\n        return readPrimitive(key, Primitive.String, def);\n    }\n\n    /**\n     * Get a number environment variable with optional fallback.\n     * Automatically converts string values to numbers.\n     * Accepts a single key or an ordered array of keys (first match wins).\n     */\n    static getNumber<Default extends number | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<number, Default> {\n        return readPrimitive(key, Primitive.Number, def);\n    }\n\n    /**\n     * @see {@link PrimitiveMethods.getNumber}\n     */\n    getNumber<Default extends number | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<number, Default> {\n        return readPrimitive(key, Primitive.Number, def);\n    }\n\n    /**\n     * Get a boolean environment variable with optional fallback.\n     * Recognizes: `1`, `yes`, `true`, `on` as **true**; `0`, `no`, `false`, `off` as **false** (case-insensitive).\n     * Accepts a single key or an ordered array of keys (first match wins).\n     */\n    static getBoolean<Default extends boolean | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<boolean, Default> {\n        return readPrimitive(key, Primitive.Boolean, def);\n    }\n\n    /**\n     * @see {@link PrimitiveMethods.getBoolean}\n     */\n    getBoolean<Default extends boolean | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<boolean, Default> {\n        return readPrimitive(key, Primitive.Boolean, def);\n    }\n\n    /**\n     * Get a bigint environment variable with optional fallback.\n     * Automatically converts string values to bigint.\n     * Accepts a single key or an ordered array of keys (first match wins).\n     */\n    static getBigInt<Default extends bigint | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<bigint, Default> {\n        return readPrimitive(key, Primitive.BigInt, def);\n    }\n\n    /**\n     * @see {@link PrimitiveMethods.getBigInt}\n     */\n    getBigInt<Default extends bigint | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<bigint, Default> {\n        return readPrimitive(key, Primitive.BigInt, def);\n    }\n\n    /**\n     * Get a symbol environment variable with optional fallback.\n     * Creates a symbol from the string value.\n     * Accepts a single key or an ordered array of keys (first match wins).\n     */\n    static getSymbol<Default extends symbol | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<symbol, Default> {\n        return readPrimitive(key, Primitive.Symbol, def);\n    }\n\n    /**\n     * @see {@link PrimitiveMethods.getSymbol}\n     */\n    getSymbol<Default extends symbol | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<symbol, Default> {\n        return readPrimitive(key, Primitive.Symbol, def);\n    }\n}\n"],"mappings":"2GAQA,IAAa,EAAb,cAAsC,CAAmB,CAMrD,OAAO,IACH,EACA,EACkC,CAClC,OAAO,EAAc,EAAA,EAAuB,CAAG,CACnD,CAKA,IACI,EACA,EACkC,CAClC,OAAO,EAAc,EAAA,EAAuB,CAAG,CACnD,CAOA,OAAO,UACH,EACA,EACkC,CAClC,OAAO,EAAc,EAAA,EAAuB,CAAG,CACnD,CAKA,UACI,EACA,EACkC,CAClC,OAAO,EAAc,EAAA,EAAuB,CAAG,CACnD,CAOA,OAAO,WACH,EACA,EACmC,CACnC,OAAO,EAAc,EAAA,EAAwB,CAAG,CACpD,CAKA,WACI,EACA,EACmC,CACnC,OAAO,EAAc,EAAA,EAAwB,CAAG,CACpD,CAOA,OAAO,UACH,EACA,EACkC,CAClC,OAAO,EAAc,EAAA,EAAuB,CAAG,CACnD,CAKA,UACI,EACA,EACkC,CAClC,OAAO,EAAc,EAAA,EAAuB,CAAG,CACnD,CAOA,OAAO,UACH,EACA,EACkC,CAClC,OAAO,EAAc,EAAA,EAAuB,CAAG,CACnD,CAKA,UACI,EACA,EACkC,CAClC,OAAO,EAAc,EAAA,EAAuB,CAAG,CACnD,CACJ"}
+{"version":3,"file":"PrimitiveMethods.mjs","names":[],"sources":["../../../src/core/PrimitiveMethods.ts"],"sourcesContent":["import { Primitive, readPrimitive } from './engine';\nimport { EnvironmentMethods } from './EnvironmentMethods';\n\nimport type { ConditionalReturn, EnvKeyInput } from '../types';\n\n/**\n * @internal\n */\nexport class PrimitiveMethods extends EnvironmentMethods {\n    /**\n     * Get a string environment variable with optional fallback.\n     * Supports template variable resolution using `${VAR}` syntax.\n     * Accepts a single key or an ordered array of keys (first match wins).\n     * @see {@link https://envapt.materwelon.dev/docs/envapter#primitives}\n     */\n    static get<Default extends string | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<string, Default> {\n        return readPrimitive(key, Primitive.String, def);\n    }\n\n    /**\n     * @see {@link PrimitiveMethods.get}\n     */\n    get<Default extends string | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<string, Default> {\n        return readPrimitive(key, Primitive.String, def);\n    }\n\n    /**\n     * Get a number environment variable with optional fallback.\n     * Automatically converts string values to numbers.\n     * Accepts a single key or an ordered array of keys (first match wins).\n     * @see {@link https://envapt.materwelon.dev/docs/envapter#primitives}\n     */\n    static getNumber<Default extends number | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<number, Default> {\n        return readPrimitive(key, Primitive.Number, def);\n    }\n\n    /**\n     * @see {@link PrimitiveMethods.getNumber}\n     */\n    getNumber<Default extends number | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<number, Default> {\n        return readPrimitive(key, Primitive.Number, def);\n    }\n\n    /**\n     * Get a boolean environment variable with optional fallback.\n     * Recognizes: `1`, `yes`, `true`, `on` as **true**; `0`, `no`, `false`, `off` as **false** (case-insensitive).\n     * Accepts a single key or an ordered array of keys (first match wins).\n     * @see {@link https://envapt.materwelon.dev/docs/envapter#primitives}\n     */\n    static getBoolean<Default extends boolean | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<boolean, Default> {\n        return readPrimitive(key, Primitive.Boolean, def);\n    }\n\n    /**\n     * @see {@link PrimitiveMethods.getBoolean}\n     */\n    getBoolean<Default extends boolean | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<boolean, Default> {\n        return readPrimitive(key, Primitive.Boolean, def);\n    }\n\n    /**\n     * Get a bigint environment variable with optional fallback.\n     * Automatically converts string values to bigint.\n     * Accepts a single key or an ordered array of keys (first match wins).\n     * @see {@link https://envapt.materwelon.dev/docs/envapter#primitives}\n     */\n    static getBigInt<Default extends bigint | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<bigint, Default> {\n        return readPrimitive(key, Primitive.BigInt, def);\n    }\n\n    /**\n     * @see {@link PrimitiveMethods.getBigInt}\n     */\n    getBigInt<Default extends bigint | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<bigint, Default> {\n        return readPrimitive(key, Primitive.BigInt, def);\n    }\n\n    /**\n     * Get a symbol environment variable with optional fallback.\n     * Creates a symbol from the string value.\n     * Accepts a single key or an ordered array of keys (first match wins).\n     * @see {@link https://envapt.materwelon.dev/docs/envapter#primitives}\n     */\n    static getSymbol<Default extends symbol | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<symbol, Default> {\n        return readPrimitive(key, Primitive.Symbol, def);\n    }\n\n    /**\n     * @see {@link PrimitiveMethods.getSymbol}\n     */\n    getSymbol<Default extends symbol | undefined = undefined>(\n        key: EnvKeyInput,\n        def?: Default\n    ): ConditionalReturn<symbol, Default> {\n        return readPrimitive(key, Primitive.Symbol, def);\n    }\n}\n"],"mappings":"2GAQA,IAAa,EAAb,cAAsC,CAAmB,CAOrD,OAAO,IACH,EACA,EACkC,CAClC,OAAO,EAAc,EAAA,EAAuB,CAAG,CACnD,CAKA,IACI,EACA,EACkC,CAClC,OAAO,EAAc,EAAA,EAAuB,CAAG,CACnD,CAQA,OAAO,UACH,EACA,EACkC,CAClC,OAAO,EAAc,EAAA,EAAuB,CAAG,CACnD,CAKA,UACI,EACA,EACkC,CAClC,OAAO,EAAc,EAAA,EAAuB,CAAG,CACnD,CAQA,OAAO,WACH,EACA,EACmC,CACnC,OAAO,EAAc,EAAA,EAAwB,CAAG,CACpD,CAKA,WACI,EACA,EACmC,CACnC,OAAO,EAAc,EAAA,EAAwB,CAAG,CACpD,CAQA,OAAO,UACH,EACA,EACkC,CAClC,OAAO,EAAc,EAAA,EAAuB,CAAG,CACnD,CAKA,UACI,EACA,EACkC,CAClC,OAAO,EAAc,EAAA,EAAuB,CAAG,CACnD,CAQA,OAAO,UACH,EACA,EACkC,CAClC,OAAO,EAAc,EAAA,EAAuB,CAAG,CACnD,CAKA,UACI,EACA,EACkC,CAClC,OAAO,EAAc,EAAA,EAAuB,CAAG,CACnD,CACJ"}

package/dist/node/core/engine.cjs

@@ -1,2 +1,2 @@
-const e=require("./Environment.cjs"),t=require("../infra/Error.cjs"),n=require("../converters/BuiltInConverters.cjs"),r=require("./state.cjs"),i=require("../converters/ValueConverter.cjs"),a=require("./paths.cjs"),o=require("../infra/Debug.cjs"),s=require("../engine/TemplateResolver.cjs"),c=require("../infra/Dotenv.cjs");function l(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=d().get(e);if(t!==void 0)return{key:e,value:t}}return{key:n[0],value:void 0}}function u(e){return!!(e===void 0||e===``||r.state.strict&&e.trim()===``)}function d(){if(!r.state.cacheBuilt){let e=r.state.source,t={...e.readVars()},n=new Set;if(e.supportsFiles){o.debugVerbose(`base dir: ${r.state.baseDir??`working directory`}`);let i=a.resolveEffectivePaths();o.debugVerbose(`effective .env paths: ${i.length===0?`(none)`:i.join(`, `)}`);try{n=c.loadDotenv({...r.state.userDefinedEnvFileOptions,path:i,processEnv:t,readFile:e.readFile.bind(e)})}catch(e){o.debugWarn(`failed to load .env: ${e instanceof Error?e.message:String(e)}`)}}r.state.dotenvAddedKeys=n;for(let[e,n]of Object.entries(t))r.cache.set(e,n);o.debugVerbose(`cache populated: ${r.cache.size} keys total`),r.state.cacheBuilt=!0,r.state.syncProcessEnv&&p()}return r.cache}function f(){r.state.environmentExplicitlySet||(r.state.environment=void 0),r.cache.clear(),r.state.cacheBuilt=!1,r.state.dotenvAddedKeys=new Set,o.debugVerbose(`cache cleared, reloading config`),d()}function p(){if(r.state.dotenvAddedKeys.size===0)return;let e=r.state.source;if(!e.supportsFiles)return;let t={};for(let e of r.state.dotenvAddedKeys){let n=r.cache.get(e);typeof n==`string`&&(t[e]=m(e,n),o.debugVerbose(`mirrored ${e} to the ambient environment`))}e.writeVars(t),o.debugVerbose(`mirrored ${r.state.dotenvAddedKeys.size} keys to the ambient environment`)}function m(e,t){return _.resolveTemplate(e,t)}function h(t){if(typeof t==`number`){r.state.environment=t,r.state.environmentExplicitlySet=!0;return}if(typeof t==`string`){r.state.environment=e.parseEnvironment(t)??0,r.state.environmentExplicitlySet=!0;return}let n=e.firstEnvKeyValue(e=>{let t=d().get(e);return typeof t==`string`?t:void 0});if(n===void 0){o.debugWarn(`no environment set (looked for ${e.ENV_KEYS.join(`, `)}); defaulting to development`),r.state.environment=0;return}let i=e.parseEnvironment(n);if(i===void 0){o.debugWarn(`unrecognized environment "${n}"; defaulting to development`),r.state.environment=0;return}r.state.environment=i}const g={getRaw:e=>l(e).value,get:(e,t)=>y(e,0,t)},_=new s.TemplateResolver(g),v=new i.ValueConverter(g);function y(e,t,r){let{key:i,value:a}=l(e);if(u(a))return r===void 0?o.debugWarn(`${i} is missing or empty`):o.debugWarn(`${i} is missing or empty, using fallback ${String(r)}`),r;let s=_.resolveTemplate(i,String(a)),c;return c=t===1?n.BuiltInConverters.number(s,r):t===2?n.BuiltInConverters.boolean(s,r):t===3?n.BuiltInConverters.bigint(s,r):t===4?n.BuiltInConverters.symbol(s,r):n.BuiltInConverters.string(s,r),c}exports.determineEnvironment=h,exports.ensureLoaded=d,exports.mirrorToProcessEnv=p,exports.readPrimitive=y,exports.refreshCache=f,exports.resolveKeyInput=l,exports.templateResolver=_,exports.treatAsMissing=u,exports.valueConverter=v;
+const e=require("../infra/Error.cjs"),t=require("./state.cjs"),n=require("./missing.cjs"),r=require("./Environment.cjs"),i=require("../converters/BuiltInConverters.cjs"),a=require("../infra/Debug.cjs"),o=require("../converters/ValueConverter.cjs"),s=require("./paths.cjs"),c=require("../engine/TemplateResolver.cjs"),l=require("../infra/Dotenv.cjs");function u(t){let r=Array.isArray(t)?t:[t];if(r.length===0)throw new e.EnvaptError(304,`At least one environment key must be provided.`);if(r.some(e=>typeof e!=`string`))throw new e.EnvaptError(304,`Environment keys must be strings.`);if(r.some(e=>e.trim()===``))throw new e.EnvaptError(304,`Environment keys cannot be empty strings.`);let i;for(let e of r){let t=f(e);if(t!==void 0){if(!n.isMissing(t))return{key:e,value:t};i??={key:e,value:t}}}return i??{key:r[0],value:void 0}}function d(){if(!t.state.cacheBuilt){let e=t.state.source,n={...e.readVars()},r=new Set;if(e.supportsFiles){a.debugVerbose(`base dir: ${t.state.baseDir??`working directory`}`);let i=s.resolveEffectivePaths();a.debugVerbose(`effective .env paths: ${i.length===0?`(none)`:i.join(`, `)}`);try{r=l.loadDotenv({...t.state.userDefinedEnvFileOptions,path:i,processEnv:n,readFile:e.readFile.bind(e)})}catch(e){a.debugWarn(`failed to load .env: ${e instanceof Error?e.message:String(e)}`)}}t.state.dotenvAddedKeys=r;for(let[e,r]of Object.entries(n))t.cache.set(e,r);a.debugVerbose(`cache populated: ${t.cache.size} keys total`),t.state.cacheBuilt=!0,t.state.syncProcessEnv&&m()}return t.cache}function f(e){let n=d();if(n.has(e)){let t=n.get(e);return typeof t==`string`?t:void 0}let r=t.state.source;if(typeof r.readVar!=`function`)return;let i=r.readVar(e);return n.set(e,i),i}function p(){t.state.environmentExplicitlySet||(t.state.environment=void 0),t.cache.clear(),t.state.cacheBuilt=!1,t.state.dotenvAddedKeys=new Set,a.debugVerbose(`cache cleared, reloading config`),d()}function m(){if(t.state.dotenvAddedKeys.size===0)return;let e=t.state.source;if(!e.supportsFiles)return;let n={};for(let e of t.state.dotenvAddedKeys){let r=t.cache.get(e);typeof r==`string`&&(n[e]=h(e,r),a.debugVerbose(`mirrored ${e} to the ambient environment`))}e.writeVars(n),a.debugVerbose(`mirrored ${t.state.dotenvAddedKeys.size} keys to the ambient environment`)}function h(e,t){return y.resolveTemplate(e,t)}function g(e){if(typeof e==`number`){t.state.environment=e,t.state.environmentExplicitlySet=!0;return}if(typeof e==`string`){t.state.environment=r.parseEnvironment(e)??0,t.state.environmentExplicitlySet=!0;return}let n=r.firstEnvKeyValue(e=>f(e));if(n===void 0){a.debugWarn(`no environment set (looked for ${r.ENV_KEYS.join(`, `)}); defaulting to development`),t.state.environment=0;return}let i=r.parseEnvironment(n);if(i===void 0){a.debugWarn(`unrecognized environment "${n}"; defaulting to development`),t.state.environment=0;return}t.state.environment=i}const _={0:`string`,1:`number`,2:`boolean`,3:`bigint`,4:`symbol`},v={getRaw:e=>u(e).value,get:(e,t)=>x(e,0,t)},y=new c.TemplateResolver(v),b=new o.ValueConverter(v);function x(e,t,r){let{key:o,value:s}=u(e);if(n.isMissing(s))return r===void 0?a.debugWarn(`${o} is missing or empty`):a.debugWarn(`${o} is missing or empty, using fallback ${String(r)}`),r;let c=y.resolveTemplate(o,String(s)),l;return l=t===1?i.BuiltInConverters.number(c):t===2?i.BuiltInConverters.boolean(c):t===3?i.BuiltInConverters.bigint(c):t===4?i.BuiltInConverters.symbol(c):i.BuiltInConverters.string(c),l===void 0?(a.debugVerbose(`could not convert ${o} as ${_[t]}${r===void 0?``:`, using the fallback`}`),r):l}exports.determineEnvironment=g,exports.ensureLoaded=d,exports.mirrorToProcessEnv=m,exports.readPrimitive=x,exports.refreshCache=p,exports.resolveKeyInput=u,exports.templateResolver=y,exports.valueConverter=b;
 //# sourceMappingURL=engine.cjs.map

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

@@ -1 +1 @@
-{"version":3,"file":"engine.cjs","names":["EnvaptError","state","resolveEffectivePaths","loadDotenv","cache","parseEnvironment","firstEnvKeyValue","ENV_KEYS","TemplateResolver","ValueConverter","BuiltInConverters"],"sources":["../../../src/core/engine.ts"],"sourcesContent":["import { BuiltInConverters, ValueConverter } from '../converters';\nimport { ENV_KEYS, Environment, firstEnvKeyValue, parseEnvironment } from './Environment';\nimport { resolveEffectivePaths } from './paths';\nimport { cache, state } from './state';\nimport { TemplateResolver } from '../engine/TemplateResolver';\nimport { debugVerbose, debugWarn } from '../infra/Debug';\nimport { loadDotenv } from '../infra/Dotenv';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { ConditionalReturn, EnvKeyInput } from '../types';\nimport type { EnvapterService } from '../types/Env';\n\nexport function 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 = ensureLoaded().get(candidate) as string | undefined;\n        if (value !== undefined) return { key: candidate, value };\n    }\n\n    return { key: normalizedKeys[0] as string, value: undefined };\n}\n\nexport function treatAsMissing(value: string | undefined): boolean {\n    if (value === undefined || value === '') return true;\n    if (state.strict && value.trim() === '') return true;\n    return false;\n}\n\nexport function ensureLoaded(): Map<string, unknown> {\n    if (!state.cacheBuilt) {\n        const source = state.source;\n        // Clone so the loader and downstream reads never mutate the source's backing object.\n        const isolatedEnv: Record<string, string> = { ...source.readVars() };\n\n        let added = new Set<string>();\n        // Sources without a filesystem (injected objects on the browser or Workers) skip the .env\n        // cascade, profiles, and envPaths. Only the readVars() snapshot populates the cache.\n        if (source.supportsFiles) {\n            debugVerbose(`base dir: ${state.baseDir ?? 'working directory'}`);\n            // Outside the try below so a missing configured profile path surfaces its EnvaptError. Only dotenv parse errors stay caught.\n            const effectivePaths = resolveEffectivePaths();\n            debugVerbose(`effective .env paths: ${effectivePaths.length === 0 ? '(none)' : effectivePaths.join(', ')}`);\n            try {\n                added = loadDotenv({\n                    ...state.userDefinedEnvFileOptions,\n                    path: effectivePaths,\n                    processEnv: isolatedEnv,\n                    readFile: source.readFile.bind(source)\n                });\n            } catch (error) {\n                debugWarn(`failed to load .env: ${error instanceof Error ? error.message : String(error)}`);\n            }\n        }\n        state.dotenvAddedKeys = added;\n        for (const [key, value] of Object.entries(isolatedEnv)) cache.set(key, value);\n        debugVerbose(`cache populated: ${cache.size} keys total`);\n        // set before mirroring, whose template expansion reads the cache and would re-enter this build otherwise\n        state.cacheBuilt = true;\n        if (state.syncProcessEnv) mirrorToProcessEnv();\n    }\n\n    return cache;\n}\n\nexport function refreshCache(): void {\n    // Reset an inferred environment so re-hydration re-determines it from current state. An explicit\n    // Envapter.environment = X is preserved through the refresh and used for cascade selection.\n    if (!state.environmentExplicitlySet) state.environment = undefined;\n    cache.clear();\n    state.cacheBuilt = false;\n    state.dotenvAddedKeys = new Set<string>();\n    debugVerbose('cache cleared, reloading config');\n    ensureLoaded();\n}\n\nexport function mirrorToProcessEnv(): void {\n    if (state.dotenvAddedKeys.size === 0) return;\n    const source = state.source;\n    /* v8 ignore next -- @preserve dotenv keys only accumulate under a file source, so the delta implies supportsFiles here */\n    if (!source.supportsFiles) return;\n    const mirrored: Record<string, string> = {};\n    for (const key of state.dotenvAddedKeys) {\n        const value = cache.get(key);\n        /* v8 ignore next -- @preserve loader only writes strings, defensive against future cache contents */\n        if (typeof value !== 'string') continue;\n        mirrored[key] = resolveForMirror(key, value);\n        debugVerbose(`mirrored ${key} to the ambient environment`);\n    }\n    source.writeVars(mirrored);\n    debugVerbose(`mirrored ${state.dotenvAddedKeys.size} keys to the ambient environment`);\n}\n\nfunction resolveForMirror(key: string, value: string): string {\n    return templateResolver.resolveTemplate(key, value);\n}\n\nexport function determineEnvironment(env?: string | Environment): void {\n    if (typeof env === 'number') {\n        state.environment = env;\n        state.environmentExplicitlySet = true;\n        return;\n    }\n    if (typeof env === 'string') {\n        state.environment = parseEnvironment(env) ?? Environment.Development;\n        state.environmentExplicitlySet = true;\n        return;\n    }\n\n    const raw = firstEnvKeyValue((key) => {\n        const value = ensureLoaded().get(key);\n        return typeof value === 'string' ? value : undefined;\n    });\n    if (raw === undefined) {\n        debugWarn(`no environment set (looked for ${ENV_KEYS.join(', ')}); defaulting to development`);\n        state.environment = Environment.Development;\n        return;\n    }\n    const parsed = parseEnvironment(raw);\n    if (parsed === undefined) {\n        debugWarn(`unrecognized environment \"${raw}\"; defaulting to development`);\n        state.environment = Environment.Development;\n        return;\n    }\n    state.environment = parsed;\n}\n\n/**\n * @internal\n */\nexport enum Primitive {\n    String,\n    Number,\n    Boolean,\n    BigInt,\n    Symbol\n}\n\n// getRaw is the raw string lookup, get is the template-resolved string read. Lazy arrows so the\n// resolver singletons below store envService without calling readPrimitive, which reads\n// templateResolver before it is assigned.\nconst envService: EnvapterService = {\n    getRaw: (key) => resolveKeyInput(key).value,\n    get: (key, def) => readPrimitive<string, string | undefined>(key, Primitive.String, def)\n};\n\nexport const templateResolver: TemplateResolver = new TemplateResolver(envService);\nexport const valueConverter: ValueConverter = new ValueConverter(envService);\n\nexport function readPrimitive<EnvVarReturnType, DefaultType extends EnvVarReturnType | undefined = undefined>(\n    key: EnvKeyInput,\n    type: Primitive,\n    def?: DefaultType\n): ConditionalReturn<EnvVarReturnType, DefaultType> {\n    const { key: resolvedKey, value } = resolveKeyInput(key);\n    if (treatAsMissing(value)) {\n        if (def !== undefined) debugWarn(`${resolvedKey} is missing or empty, using fallback ${String(def)}`);\n        else debugWarn(`${resolvedKey} is missing or empty`);\n        return def as ConditionalReturn<EnvVarReturnType, DefaultType>;\n    }\n\n    const parsed = templateResolver.resolveTemplate(resolvedKey, String(value));\n\n    let result: EnvVarReturnType;\n    if (type === Primitive.Number) result = BuiltInConverters.number(parsed, def as number) as EnvVarReturnType;\n    else if (type === Primitive.Boolean) result = BuiltInConverters.boolean(parsed, def as boolean) as EnvVarReturnType;\n    else if (type === Primitive.BigInt) result = BuiltInConverters.bigint(parsed, def as bigint) as EnvVarReturnType;\n    else if (type === Primitive.Symbol) result = BuiltInConverters.symbol(parsed, def as symbol) as EnvVarReturnType;\n    else result = BuiltInConverters.string(parsed, def as string) as EnvVarReturnType;\n\n    return result;\n}\n"],"mappings":"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"}
+{"version":3,"file":"engine.cjs","names":["EnvaptError","isMissing","state","resolveEffectivePaths","loadDotenv","cache","parseEnvironment","firstEnvKeyValue","ENV_KEYS","TemplateResolver","ValueConverter","BuiltInConverters"],"sources":["../../../src/core/engine.ts"],"sourcesContent":["import { BuiltInConverters, ValueConverter } from '../converters';\nimport { ENV_KEYS, Environment, firstEnvKeyValue, parseEnvironment } from './Environment';\nimport { isMissing } from './missing';\nimport { resolveEffectivePaths } from './paths';\nimport { cache, state } from './state';\nimport { TemplateResolver } from '../engine/TemplateResolver';\nimport { debugVerbose, debugWarn } from '../infra/Debug';\nimport { loadDotenv } from '../infra/Dotenv';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { ConditionalReturn, EnvKeyInput } from '../types';\nimport type { EnvapterService } from '../types/Env';\n\nexport function 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    // An ordered read keeps trying so a present-but-empty candidate falls through to the next, matching\n    // getRequired and firstEnvKeyValue. A single key or an all-empty list resolves to the first present value.\n    let firstPresent: { key: string; value: string } | undefined;\n    for (const candidate of normalizedKeys) {\n        const value = readCached(candidate);\n        if (value === undefined) continue;\n        if (!isMissing(value)) return { key: candidate, value };\n        firstPresent ??= { key: candidate, value };\n    }\n\n    return firstPresent ?? { key: normalizedKeys[0] as string, value: undefined };\n}\n\nexport function ensureLoaded(): Map<string, unknown> {\n    if (!state.cacheBuilt) {\n        const source = state.source;\n        // Clone so the loader and downstream reads never mutate the source's backing object.\n        const isolatedEnv: Record<string, string> = { ...source.readVars() };\n\n        let added = new Set<string>();\n        // Sources without a filesystem (injected objects on the browser or Workers) skip the .env\n        // cascade, profiles, and envPaths. Only the readVars() snapshot populates the cache.\n        if (source.supportsFiles) {\n            debugVerbose(`base dir: ${state.baseDir ?? 'working directory'}`);\n            // Outside the try below so a missing configured profile path surfaces its EnvaptError. Only dotenv parse errors stay caught.\n            const effectivePaths = resolveEffectivePaths();\n            debugVerbose(`effective .env paths: ${effectivePaths.length === 0 ? '(none)' : effectivePaths.join(', ')}`);\n            try {\n                added = loadDotenv({\n                    ...state.userDefinedEnvFileOptions,\n                    path: effectivePaths,\n                    processEnv: isolatedEnv,\n                    readFile: source.readFile.bind(source)\n                });\n            } catch (error) {\n                debugWarn(`failed to load .env: ${error instanceof Error ? error.message : String(error)}`);\n            }\n        }\n        state.dotenvAddedKeys = added;\n        for (const [key, value] of Object.entries(isolatedEnv)) cache.set(key, value);\n        debugVerbose(`cache populated: ${cache.size} keys total`);\n        // set before mirroring, whose template expansion reads the cache and would re-enter this build otherwise\n        state.cacheBuilt = true;\n        if (state.syncProcessEnv) mirrorToProcessEnv();\n    }\n\n    return cache;\n}\n\nfunction readCached(key: string): string | undefined {\n    const c = ensureLoaded();\n    // decorator memoization also stores non-string values in this shared cache\n    if (c.has(key)) {\n        const cached = c.get(key);\n        return typeof cached === 'string' ? cached : undefined;\n    }\n    const source = state.source;\n    if (typeof source.readVar !== 'function') return undefined;\n    const value = source.readVar(key);\n    // cache a miss too, so a later read of an absent key skips the reader\n    c.set(key, value);\n    return value;\n}\n\nexport function refreshCache(): void {\n    // Reset an inferred environment so re-hydration re-determines it from current state. An explicit\n    // Envapter.environment = X is preserved through the refresh and used for cascade selection.\n    if (!state.environmentExplicitlySet) state.environment = undefined;\n    cache.clear();\n    state.cacheBuilt = false;\n    state.dotenvAddedKeys = new Set<string>();\n    debugVerbose('cache cleared, reloading config');\n    ensureLoaded();\n}\n\nexport function mirrorToProcessEnv(): void {\n    if (state.dotenvAddedKeys.size === 0) return;\n    const source = state.source;\n    /* v8 ignore next -- @preserve dotenv keys only accumulate under a file source, so the delta implies supportsFiles here */\n    if (!source.supportsFiles) return;\n    const mirrored: Record<string, string> = {};\n    for (const key of state.dotenvAddedKeys) {\n        const value = cache.get(key);\n        /* v8 ignore next -- @preserve loader only writes strings, defensive against future cache contents */\n        if (typeof value !== 'string') continue;\n        mirrored[key] = resolveForMirror(key, value);\n        debugVerbose(`mirrored ${key} to the ambient environment`);\n    }\n    source.writeVars(mirrored);\n    debugVerbose(`mirrored ${state.dotenvAddedKeys.size} keys to the ambient environment`);\n}\n\nfunction resolveForMirror(key: string, value: string): string {\n    return templateResolver.resolveTemplate(key, value);\n}\n\nexport function determineEnvironment(env?: string | Environment): void {\n    if (typeof env === 'number') {\n        state.environment = env;\n        state.environmentExplicitlySet = true;\n        return;\n    }\n    if (typeof env === 'string') {\n        state.environment = parseEnvironment(env) ?? Environment.Development;\n        state.environmentExplicitlySet = true;\n        return;\n    }\n\n    const raw = firstEnvKeyValue((key) => readCached(key));\n    if (raw === undefined) {\n        debugWarn(`no environment set (looked for ${ENV_KEYS.join(', ')}); defaulting to development`);\n        state.environment = Environment.Development;\n        return;\n    }\n    const parsed = parseEnvironment(raw);\n    if (parsed === undefined) {\n        debugWarn(`unrecognized environment \"${raw}\"; defaulting to development`);\n        state.environment = Environment.Development;\n        return;\n    }\n    state.environment = parsed;\n}\n\n/**\n * @internal\n */\nexport enum Primitive {\n    String,\n    Number,\n    Boolean,\n    BigInt,\n    Symbol\n}\n\nconst PRIMITIVE_NAMES: Record<Primitive, string> = {\n    [Primitive.String]: 'string',\n    [Primitive.Number]: 'number',\n    [Primitive.Boolean]: 'boolean',\n    [Primitive.BigInt]: 'bigint',\n    [Primitive.Symbol]: 'symbol'\n};\n\n// getRaw is the raw string lookup, get is the template-resolved string read. Lazy arrows so the\n// resolver singletons below store envService without calling readPrimitive, which reads\n// templateResolver before it is assigned.\nconst envService: EnvapterService = {\n    getRaw: (key) => resolveKeyInput(key).value,\n    get: (key, def) => readPrimitive<string, string | undefined>(key, Primitive.String, def)\n};\n\nexport const templateResolver: TemplateResolver = new TemplateResolver(envService);\nexport const valueConverter: ValueConverter = new ValueConverter(envService);\n\nexport function readPrimitive<EnvVarReturnType, DefaultType extends EnvVarReturnType | undefined = undefined>(\n    key: EnvKeyInput,\n    type: Primitive,\n    def?: DefaultType\n): ConditionalReturn<EnvVarReturnType, DefaultType> {\n    const { key: resolvedKey, value } = resolveKeyInput(key);\n    if (isMissing(value)) {\n        if (def !== undefined) debugWarn(`${resolvedKey} is missing or empty, using fallback ${String(def)}`);\n        else debugWarn(`${resolvedKey} is missing or empty`);\n        return def as ConditionalReturn<EnvVarReturnType, DefaultType>;\n    }\n\n    const parsed = templateResolver.resolveTemplate(resolvedKey, String(value));\n\n    let converted: EnvVarReturnType | undefined;\n    if (type === Primitive.Number) converted = BuiltInConverters.number(parsed) as EnvVarReturnType | undefined;\n    else if (type === Primitive.Boolean) converted = BuiltInConverters.boolean(parsed) as EnvVarReturnType | undefined;\n    else if (type === Primitive.BigInt) converted = BuiltInConverters.bigint(parsed) as EnvVarReturnType | undefined;\n    else if (type === Primitive.Symbol) converted = BuiltInConverters.symbol(parsed) as EnvVarReturnType | undefined;\n    else converted = BuiltInConverters.string(parsed) as EnvVarReturnType | undefined;\n\n    if (converted === undefined) {\n        // key and type only, no value: env values can be secrets and verbose logs reach stderr\n        debugVerbose(\n            `could not convert ${resolvedKey} as ${PRIMITIVE_NAMES[type]}${def !== undefined ? ', using the fallback' : ''}`\n        );\n        return def as ConditionalReturn<EnvVarReturnType, DefaultType>;\n    }\n\n    return converted;\n}\n"],"mappings":"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"}

package/dist/node/core/engine.mjs

@@ -1,2 +1,2 @@
-import{ENV_KEYS as e,firstEnvKeyValue as t,parseEnvironment as n}from"./Environment.mjs";import{EnvaptError as r}from"../infra/Error.mjs";import{BuiltInConverters as i}from"../converters/BuiltInConverters.mjs";import{cache as a,state as o}from"./state.mjs";import{ValueConverter as s}from"../converters/ValueConverter.mjs";import{resolveEffectivePaths as c}from"./paths.mjs";import{debugVerbose as l,debugWarn as u}from"../infra/Debug.mjs";import{TemplateResolver as d}from"../engine/TemplateResolver.mjs";import{loadDotenv as f}from"../infra/Dotenv.mjs";function p(e){let t=Array.isArray(e)?e:[e];if(t.length===0)throw new r(304,`At least one environment key must be provided.`);if(t.some(e=>typeof e!=`string`))throw new r(304,`Environment keys must be strings.`);if(t.some(e=>e.trim()===``))throw new r(304,`Environment keys cannot be empty strings.`);for(let e of t){let t=h().get(e);if(t!==void 0)return{key:e,value:t}}return{key:t[0],value:void 0}}function m(e){return!!(e===void 0||e===``||o.strict&&e.trim()===``)}function h(){if(!o.cacheBuilt){let e=o.source,t={...e.readVars()},n=new Set;if(e.supportsFiles){l(`base dir: ${o.baseDir??`working directory`}`);let r=c();l(`effective .env paths: ${r.length===0?`(none)`:r.join(`, `)}`);try{n=f({...o.userDefinedEnvFileOptions,path:r,processEnv:t,readFile:e.readFile.bind(e)})}catch(e){u(`failed to load .env: ${e instanceof Error?e.message:String(e)}`)}}o.dotenvAddedKeys=n;for(let[e,n]of Object.entries(t))a.set(e,n);l(`cache populated: ${a.size} keys total`),o.cacheBuilt=!0,o.syncProcessEnv&&_()}return a}function g(){o.environmentExplicitlySet||(o.environment=void 0),a.clear(),o.cacheBuilt=!1,o.dotenvAddedKeys=new Set,l(`cache cleared, reloading config`),h()}function _(){if(o.dotenvAddedKeys.size===0)return;let e=o.source;if(!e.supportsFiles)return;let t={};for(let e of o.dotenvAddedKeys){let n=a.get(e);typeof n==`string`&&(t[e]=v(e,n),l(`mirrored ${e} to the ambient environment`))}e.writeVars(t),l(`mirrored ${o.dotenvAddedKeys.size} keys to the ambient environment`)}function v(e,t){return x.resolveTemplate(e,t)}function y(r){if(typeof r==`number`){o.environment=r,o.environmentExplicitlySet=!0;return}if(typeof r==`string`){o.environment=n(r)??0,o.environmentExplicitlySet=!0;return}let i=t(e=>{let t=h().get(e);return typeof t==`string`?t:void 0});if(i===void 0){u(`no environment set (looked for ${e.join(`, `)}); defaulting to development`),o.environment=0;return}let a=n(i);if(a===void 0){u(`unrecognized environment "${i}"; defaulting to development`),o.environment=0;return}o.environment=a}const b={getRaw:e=>p(e).value,get:(e,t)=>C(e,0,t)},x=new d(b),S=new s(b);function C(e,t,n){let{key:r,value:a}=p(e);if(m(a))return u(n===void 0?`${r} is missing or empty`:`${r} is missing or empty, using fallback ${String(n)}`),n;let o=x.resolveTemplate(r,String(a)),s;return s=t===1?i.number(o,n):t===2?i.boolean(o,n):t===3?i.bigint(o,n):t===4?i.symbol(o,n):i.string(o,n),s}export{y as determineEnvironment,h as ensureLoaded,_ as mirrorToProcessEnv,C as readPrimitive,g as refreshCache,p as resolveKeyInput,x as templateResolver,m as treatAsMissing,S as valueConverter};
+import{EnvaptError as e}from"../infra/Error.mjs";import{cache as t,state as n}from"./state.mjs";import{isMissing as r}from"./missing.mjs";import{ENV_KEYS as i,firstEnvKeyValue as a,parseEnvironment as o}from"./Environment.mjs";import{BuiltInConverters as s}from"../converters/BuiltInConverters.mjs";import{debugVerbose as c,debugWarn as l}from"../infra/Debug.mjs";import{ValueConverter as u}from"../converters/ValueConverter.mjs";import{resolveEffectivePaths as d}from"./paths.mjs";import{TemplateResolver as f}from"../engine/TemplateResolver.mjs";import{loadDotenv as p}from"../infra/Dotenv.mjs";function m(t){let n=Array.isArray(t)?t:[t];if(n.length===0)throw new e(304,`At least one environment key must be provided.`);if(n.some(e=>typeof e!=`string`))throw new e(304,`Environment keys must be strings.`);if(n.some(e=>e.trim()===``))throw new e(304,`Environment keys cannot be empty strings.`);let i;for(let e of n){let t=g(e);if(t!==void 0){if(!r(t))return{key:e,value:t};i??={key:e,value:t}}}return i??{key:n[0],value:void 0}}function h(){if(!n.cacheBuilt){let e=n.source,r={...e.readVars()},i=new Set;if(e.supportsFiles){c(`base dir: ${n.baseDir??`working directory`}`);let t=d();c(`effective .env paths: ${t.length===0?`(none)`:t.join(`, `)}`);try{i=p({...n.userDefinedEnvFileOptions,path:t,processEnv:r,readFile:e.readFile.bind(e)})}catch(e){l(`failed to load .env: ${e instanceof Error?e.message:String(e)}`)}}n.dotenvAddedKeys=i;for(let[e,n]of Object.entries(r))t.set(e,n);c(`cache populated: ${t.size} keys total`),n.cacheBuilt=!0,n.syncProcessEnv&&v()}return t}function g(e){let t=h();if(t.has(e)){let n=t.get(e);return typeof n==`string`?n:void 0}let r=n.source;if(typeof r.readVar!=`function`)return;let i=r.readVar(e);return t.set(e,i),i}function _(){n.environmentExplicitlySet||(n.environment=void 0),t.clear(),n.cacheBuilt=!1,n.dotenvAddedKeys=new Set,c(`cache cleared, reloading config`),h()}function v(){if(n.dotenvAddedKeys.size===0)return;let e=n.source;if(!e.supportsFiles)return;let r={};for(let e of n.dotenvAddedKeys){let n=t.get(e);typeof n==`string`&&(r[e]=y(e,n),c(`mirrored ${e} to the ambient environment`))}e.writeVars(r),c(`mirrored ${n.dotenvAddedKeys.size} keys to the ambient environment`)}function y(e,t){return C.resolveTemplate(e,t)}function b(e){if(typeof e==`number`){n.environment=e,n.environmentExplicitlySet=!0;return}if(typeof e==`string`){n.environment=o(e)??0,n.environmentExplicitlySet=!0;return}let t=a(e=>g(e));if(t===void 0){l(`no environment set (looked for ${i.join(`, `)}); defaulting to development`),n.environment=0;return}let r=o(t);if(r===void 0){l(`unrecognized environment "${t}"; defaulting to development`),n.environment=0;return}n.environment=r}const x={0:`string`,1:`number`,2:`boolean`,3:`bigint`,4:`symbol`},S={getRaw:e=>m(e).value,get:(e,t)=>T(e,0,t)},C=new f(S),w=new u(S);function T(e,t,n){let{key:i,value:a}=m(e);if(r(a))return l(n===void 0?`${i} is missing or empty`:`${i} is missing or empty, using fallback ${String(n)}`),n;let o=C.resolveTemplate(i,String(a)),u;return u=t===1?s.number(o):t===2?s.boolean(o):t===3?s.bigint(o):t===4?s.symbol(o):s.string(o),u===void 0?(c(`could not convert ${i} as ${x[t]}${n===void 0?``:`, using the fallback`}`),n):u}export{b as determineEnvironment,h as ensureLoaded,v as mirrorToProcessEnv,T as readPrimitive,_ as refreshCache,m as resolveKeyInput,C as templateResolver,w as valueConverter};
 //# sourceMappingURL=engine.mjs.map