envapt 6.0.2 → 7.0.0-next.0

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

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

package/dist/node/core/EnvironmentMethods.d.cts

@@ -1,5 +1,5 @@
-import { EnvapterBase } from "./EnvapterBase.cjs";
 import { ProfilesConfig } from "../types/Options.cjs";
+import { EnvapterBase } from "./EnvapterBase.cjs";
 
 //#region src/core/EnvironmentMethods.d.ts
 /**

package/dist/node/core/EnvironmentMethods.d.mts

@@ -1,7 +1,7 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { EnvapterBase } from "./EnvapterBase.mjs";
 import { ProfilesConfig } from "../types/Options.mjs";
+import { EnvapterBase } from "./EnvapterBase.mjs";
 
 //#region src/core/EnvironmentMethods.d.ts
 /**

package/dist/node/core/EnvironmentMethods.mjs

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

package/dist/node/core/PrimitiveMethods.cjs

@@ -1,2 +1,2 @@
-import"node:path";import"node:url";import.meta.url;const e=require("../converters/BuiltInConverters.cjs"),t=require("../converters/ValueConverter.cjs"),n=require("../Debug.cjs"),r=require("./EnvapterBase.cjs"),i=require("./EnvironmentMethods.cjs"),a=require("../TemplateResolver.cjs");var o=class o extends i.EnvironmentMethods{static service=new o;static templateResolver=new a.TemplateResolver(o.service);static valueConverter=new t.ValueConverter(o.service);isStrict(){return r.EnvapterBase.strict}static _get(t,r,i){let{key:a,value:o}=this.resolveKeyInput(t);if(this.treatAsMissing(o))return i!==void 0&&n.debugWarn(`${a} not found, using fallback ${String(i)}`),i;let s=o,c=this.templateResolver.resolveTemplate(a,String(s)),l;return l=r===1?e.BuiltInConverters.number(c,i):r===2?e.BuiltInConverters.boolean(c,i):r===3?e.BuiltInConverters.bigint(c,i):r===4?e.BuiltInConverters.symbol(c,i):e.BuiltInConverters.string(c,i),l}static get(e,t){return this._get(e,0,t)}get(e,t){return o._get(e,0,t)}static getNumber(e,t){return this._get(e,1,t)}getNumber(e,t){return o._get(e,1,t)}static getBoolean(e,t){return this._get(e,2,t)}getBoolean(e,t){return o._get(e,2,t)}static getBigInt(e,t){return this._get(e,3,t)}getBigInt(e,t){return o._get(e,3,t)}static getSymbol(e,t){return this._get(e,4,t)}getSymbol(e,t){return o._get(e,4,t)}};exports.PrimitiveMethods=o;
+import"node:path";import"node:url";import.meta.url;const e=require("../infra/Debug.cjs"),t=require("./EnvapterBase.cjs"),n=require("./EnvironmentMethods.cjs"),r=require("../converters/BuiltInConverters.cjs"),i=require("../converters/ValueConverter.cjs"),a=require("../engine/TemplateResolver.cjs");var o=class o extends n.EnvironmentMethods{static service=new o;static templateResolver=new a.TemplateResolver(o.service);static valueConverter=new i.ValueConverter(o.service);isStrict(){return t.EnvapterBase.strict}static _get(t,n,i){let{key:a,value:o}=this.resolveKeyInput(t);if(this.treatAsMissing(o))return i!==void 0&&e.debugWarn(`${a} not found, using fallback ${String(i)}`),i;let s=o,c=this.templateResolver.resolveTemplate(a,String(s)),l;return l=n===1?r.BuiltInConverters.number(c,i):n===2?r.BuiltInConverters.boolean(c,i):n===3?r.BuiltInConverters.bigint(c,i):n===4?r.BuiltInConverters.symbol(c,i):r.BuiltInConverters.string(c,i),l}static get(e,t){return this._get(e,0,t)}get(e,t){return o._get(e,0,t)}static getNumber(e,t){return this._get(e,1,t)}getNumber(e,t){return o._get(e,1,t)}static getBoolean(e,t){return this._get(e,2,t)}getBoolean(e,t){return o._get(e,2,t)}static getBigInt(e,t){return this._get(e,3,t)}getBigInt(e,t){return o._get(e,3,t)}static getSymbol(e,t){return this._get(e,4,t)}getSymbol(e,t){return o._get(e,4,t)}};exports.PrimitiveMethods=o;
 //# sourceMappingURL=PrimitiveMethods.cjs.map

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

@@ -1 +1 @@
-{"version":3,"file":"PrimitiveMethods.cjs","names":["EnvironmentMethods","TemplateResolver","ValueConverter","EnvapterBase","BuiltInConverters"],"sources":["../../../src/core/PrimitiveMethods.ts"],"sourcesContent":["import { BuiltInConverters, ValueConverter } from '../converters';\nimport { debugWarn } from '../Debug';\nimport { TemplateResolver } from '../TemplateResolver';\nimport { EnvapterBase } from './EnvapterBase';\nimport { EnvironmentMethods } from './EnvironmentMethods';\n\nimport type { ConditionalReturn, EnvKeyInput } from '../types';\nimport type { EnvapterService } from '../types/Env';\n\n/**\n * @internal\n */\nenum Primitive {\n    String,\n    Number,\n    Boolean,\n    BigInt,\n    Symbol\n}\n\n/**\n * @internal\n */\nexport class PrimitiveMethods extends EnvironmentMethods implements EnvapterService {\n    private static readonly service = new PrimitiveMethods();\n    protected static readonly templateResolver: TemplateResolver = new TemplateResolver(PrimitiveMethods.service);\n    protected static readonly valueConverter: ValueConverter = new ValueConverter(PrimitiveMethods.service);\n\n    // Read `EnvapterBase.strict` directly: `PrimitiveMethods._strict` would resolve to the\n    // BaseClass default because a `Envapter.strict = true` write lands as an own-property\n    // on `Envapter`, which is a descendant of `PrimitiveMethods`, not an ancestor.\n    isStrict(): boolean {\n        return EnvapterBase.strict;\n    }\n\n    private static _get<EnvVarReturnType, DefaultType extends EnvVarReturnType | undefined = undefined>(\n        key: EnvKeyInput,\n        type: Primitive,\n        def?: DefaultType\n    ): ConditionalReturn<EnvVarReturnType, DefaultType> {\n        const { key: resolvedKey, value } = this.resolveKeyInput(key);\n        if (this.treatAsMissing(value)) {\n            if (def !== undefined) debugWarn(`${resolvedKey} not found, using fallback ${String(def)}`);\n            return def as ConditionalReturn<EnvVarReturnType, DefaultType>;\n        }\n        const rawVal = value as string | number | boolean | undefined;\n\n        const parsed = this.templateResolver.resolveTemplate(resolvedKey, String(rawVal));\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)\n            result = BuiltInConverters.boolean(parsed, def as boolean) as EnvVarReturnType;\n        else if (type === Primitive.BigInt)\n            result = BuiltInConverters.bigint(parsed, def as bigint) as EnvVarReturnType;\n        else if (type === Primitive.Symbol)\n            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\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 this._get(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 PrimitiveMethods._get(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 this._get(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 PrimitiveMethods._get(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 this._get(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 PrimitiveMethods._get(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 this._get(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 PrimitiveMethods._get(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 this._get(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 PrimitiveMethods._get(key, Primitive.Symbol, def);\n    }\n}\n"],"mappings":"6RAuBA,IAAa,EAAb,MAAa,UAAyBA,EAAAA,kBAA8C,CAChF,OAAwB,QAAU,IAAI,EACtC,OAA0B,iBAAqC,IAAIC,EAAAA,iBAAiB,EAAiB,OAAO,EAC5G,OAA0B,eAAiC,IAAIC,EAAAA,eAAe,EAAiB,OAAO,EAKtG,UAAoB,CAChB,OAAOC,EAAAA,aAAa,MACxB,CAEA,OAAe,KACX,EACA,EACA,EACgD,CAChD,GAAM,CAAE,IAAK,EAAa,SAAU,KAAK,gBAAgB,CAAG,EAC5D,GAAI,KAAK,eAAe,CAAK,EAEzB,OADI,IAAQ,IAAA,IAAW,EAAA,UAAU,GAAG,EAAY,6BAA6B,OAAO,CAAG,GAAG,EACnF,EAEX,IAAM,EAAS,EAET,EAAS,KAAK,iBAAiB,gBAAgB,EAAa,OAAO,CAAM,CAAC,EAE5E,EAUJ,MATA,CAOK,EAPD,IAAA,EAAoCC,EAAAA,kBAAkB,OAAO,EAAQ,CAAa,EAC7E,IAAA,EACIA,EAAAA,kBAAkB,QAAQ,EAAQ,CAAc,EACpD,IAAA,EACIA,EAAAA,kBAAkB,OAAO,EAAQ,CAAa,EAClD,IAAA,EACIA,EAAAA,kBAAkB,OAAO,EAAQ,CAAa,EAC7CA,EAAAA,kBAAkB,OAAO,EAAQ,CAAa,EAErD,CACX,CAOA,OAAO,IACH,EACA,EACkC,CAClC,OAAO,KAAK,KAAK,EAAA,EAAuB,CAAG,CAC/C,CAKA,IACI,EACA,EACkC,CAClC,OAAO,EAAiB,KAAK,EAAA,EAAuB,CAAG,CAC3D,CAOA,OAAO,UACH,EACA,EACkC,CAClC,OAAO,KAAK,KAAK,EAAA,EAAuB,CAAG,CAC/C,CAKA,UACI,EACA,EACkC,CAClC,OAAO,EAAiB,KAAK,EAAA,EAAuB,CAAG,CAC3D,CAOA,OAAO,WACH,EACA,EACmC,CACnC,OAAO,KAAK,KAAK,EAAA,EAAwB,CAAG,CAChD,CAKA,WACI,EACA,EACmC,CACnC,OAAO,EAAiB,KAAK,EAAA,EAAwB,CAAG,CAC5D,CAOA,OAAO,UACH,EACA,EACkC,CAClC,OAAO,KAAK,KAAK,EAAA,EAAuB,CAAG,CAC/C,CAKA,UACI,EACA,EACkC,CAClC,OAAO,EAAiB,KAAK,EAAA,EAAuB,CAAG,CAC3D,CAOA,OAAO,UACH,EACA,EACkC,CAClC,OAAO,KAAK,KAAK,EAAA,EAAuB,CAAG,CAC/C,CAKA,UACI,EACA,EACkC,CAClC,OAAO,EAAiB,KAAK,EAAA,EAAuB,CAAG,CAC3D,CACJ"}
+{"version":3,"file":"PrimitiveMethods.cjs","names":["EnvironmentMethods","TemplateResolver","ValueConverter","EnvapterBase","BuiltInConverters"],"sources":["../../../src/core/PrimitiveMethods.ts"],"sourcesContent":["import { BuiltInConverters, ValueConverter } from '../converters';\nimport { EnvapterBase } from './EnvapterBase';\nimport { EnvironmentMethods } from './EnvironmentMethods';\nimport { TemplateResolver } from '../engine/TemplateResolver';\nimport { debugWarn } from '../infra/Debug';\n\nimport type { ConditionalReturn, EnvKeyInput } from '../types';\nimport type { EnvapterService } from '../types/Env';\n\n/**\n * @internal\n */\nenum Primitive {\n    String,\n    Number,\n    Boolean,\n    BigInt,\n    Symbol\n}\n\n/**\n * @internal\n */\nexport class PrimitiveMethods extends EnvironmentMethods implements EnvapterService {\n    private static readonly service = new PrimitiveMethods();\n    protected static readonly templateResolver: TemplateResolver = new TemplateResolver(PrimitiveMethods.service);\n    protected static readonly valueConverter: ValueConverter = new ValueConverter(PrimitiveMethods.service);\n\n    // Read `EnvapterBase.strict` directly: `PrimitiveMethods._strict` would resolve to the\n    // BaseClass default because a `Envapter.strict = true` write lands as an own-property\n    // on `Envapter`, which is a descendant of `PrimitiveMethods`, not an ancestor.\n    isStrict(): boolean {\n        return EnvapterBase.strict;\n    }\n\n    private static _get<EnvVarReturnType, DefaultType extends EnvVarReturnType | undefined = undefined>(\n        key: EnvKeyInput,\n        type: Primitive,\n        def?: DefaultType\n    ): ConditionalReturn<EnvVarReturnType, DefaultType> {\n        const { key: resolvedKey, value } = this.resolveKeyInput(key);\n        if (this.treatAsMissing(value)) {\n            if (def !== undefined) debugWarn(`${resolvedKey} not found, using fallback ${String(def)}`);\n            return def as ConditionalReturn<EnvVarReturnType, DefaultType>;\n        }\n        const rawVal = value as string | number | boolean | undefined;\n\n        const parsed = this.templateResolver.resolveTemplate(resolvedKey, String(rawVal));\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)\n            result = BuiltInConverters.boolean(parsed, def as boolean) as EnvVarReturnType;\n        else if (type === Primitive.BigInt)\n            result = BuiltInConverters.bigint(parsed, def as bigint) as EnvVarReturnType;\n        else if (type === Primitive.Symbol)\n            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\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 this._get(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 PrimitiveMethods._get(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 this._get(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 PrimitiveMethods._get(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 this._get(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 PrimitiveMethods._get(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 this._get(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 PrimitiveMethods._get(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 this._get(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 PrimitiveMethods._get(key, Primitive.Symbol, def);\n    }\n}\n"],"mappings":"0SAuBA,IAAa,EAAb,MAAa,UAAyBA,EAAAA,kBAA8C,CAChF,OAAwB,QAAU,IAAI,EACtC,OAA0B,iBAAqC,IAAIC,EAAAA,iBAAiB,EAAiB,OAAO,EAC5G,OAA0B,eAAiC,IAAIC,EAAAA,eAAe,EAAiB,OAAO,EAKtG,UAAoB,CAChB,OAAOC,EAAAA,aAAa,MACxB,CAEA,OAAe,KACX,EACA,EACA,EACgD,CAChD,GAAM,CAAE,IAAK,EAAa,SAAU,KAAK,gBAAgB,CAAG,EAC5D,GAAI,KAAK,eAAe,CAAK,EAEzB,OADI,IAAQ,IAAA,IAAW,EAAA,UAAU,GAAG,EAAY,6BAA6B,OAAO,CAAG,GAAG,EACnF,EAEX,IAAM,EAAS,EAET,EAAS,KAAK,iBAAiB,gBAAgB,EAAa,OAAO,CAAM,CAAC,EAE5E,EAUJ,MATA,CAOK,EAPD,IAAA,EAAoCC,EAAAA,kBAAkB,OAAO,EAAQ,CAAa,EAC7E,IAAA,EACIA,EAAAA,kBAAkB,QAAQ,EAAQ,CAAc,EACpD,IAAA,EACIA,EAAAA,kBAAkB,OAAO,EAAQ,CAAa,EAClD,IAAA,EACIA,EAAAA,kBAAkB,OAAO,EAAQ,CAAa,EAC7CA,EAAAA,kBAAkB,OAAO,EAAQ,CAAa,EAErD,CACX,CAOA,OAAO,IACH,EACA,EACkC,CAClC,OAAO,KAAK,KAAK,EAAA,EAAuB,CAAG,CAC/C,CAKA,IACI,EACA,EACkC,CAClC,OAAO,EAAiB,KAAK,EAAA,EAAuB,CAAG,CAC3D,CAOA,OAAO,UACH,EACA,EACkC,CAClC,OAAO,KAAK,KAAK,EAAA,EAAuB,CAAG,CAC/C,CAKA,UACI,EACA,EACkC,CAClC,OAAO,EAAiB,KAAK,EAAA,EAAuB,CAAG,CAC3D,CAOA,OAAO,WACH,EACA,EACmC,CACnC,OAAO,KAAK,KAAK,EAAA,EAAwB,CAAG,CAChD,CAKA,WACI,EACA,EACmC,CACnC,OAAO,EAAiB,KAAK,EAAA,EAAwB,CAAG,CAC5D,CAOA,OAAO,UACH,EACA,EACkC,CAClC,OAAO,KAAK,KAAK,EAAA,EAAuB,CAAG,CAC/C,CAKA,UACI,EACA,EACkC,CAClC,OAAO,EAAiB,KAAK,EAAA,EAAuB,CAAG,CAC3D,CAOA,OAAO,UACH,EACA,EACkC,CAClC,OAAO,KAAK,KAAK,EAAA,EAAuB,CAAG,CAC/C,CAKA,UACI,EACA,EACkC,CAClC,OAAO,EAAiB,KAAK,EAAA,EAAuB,CAAG,CAC3D,CACJ"}

package/dist/node/core/PrimitiveMethods.d.cts

@@ -2,7 +2,7 @@ import { ConditionalReturn } from "../types/Conversion.cjs";
 import { EnvironmentMethods } from "./EnvironmentMethods.cjs";
 import { EnvKeyInput, EnvapterService } from "../types/Env.cjs";
 import { ValueConverter } from "../converters/ValueConverter.cjs";
-import { TemplateResolver } from "../TemplateResolver.cjs";
+import { TemplateResolver } from "../engine/TemplateResolver.cjs";
 
 //#region src/core/PrimitiveMethods.d.ts
 /**

package/dist/node/core/PrimitiveMethods.d.mts

@@ -4,7 +4,7 @@ import { ConditionalReturn } from "../types/Conversion.mjs";
 import { EnvironmentMethods } from "./EnvironmentMethods.mjs";
 import { EnvKeyInput, EnvapterService } from "../types/Env.mjs";
 import { ValueConverter } from "../converters/ValueConverter.mjs";
-import { TemplateResolver } from "../TemplateResolver.mjs";
+import { TemplateResolver } from "../engine/TemplateResolver.mjs";
 
 //#region src/core/PrimitiveMethods.d.ts
 /**

package/dist/node/core/PrimitiveMethods.mjs

@@ -1,2 +1,2 @@
-import"node:path";import"node:url";import.meta.url;import{BuiltInConverters as e}from"../converters/BuiltInConverters.mjs";import{ValueConverter as t}from"../converters/ValueConverter.mjs";import{debugWarn as n}from"../Debug.mjs";import{EnvapterBase as r}from"./EnvapterBase.mjs";import{EnvironmentMethods as i}from"./EnvironmentMethods.mjs";import{TemplateResolver as a}from"../TemplateResolver.mjs";var o=class o extends i{static service=new o;static templateResolver=new a(o.service);static valueConverter=new t(o.service);isStrict(){return r.strict}static _get(t,r,i){let{key:a,value:o}=this.resolveKeyInput(t);if(this.treatAsMissing(o))return i!==void 0&&n(`${a} not found, using fallback ${String(i)}`),i;let s=o,c=this.templateResolver.resolveTemplate(a,String(s)),l;return l=r===1?e.number(c,i):r===2?e.boolean(c,i):r===3?e.bigint(c,i):r===4?e.symbol(c,i):e.string(c,i),l}static get(e,t){return this._get(e,0,t)}get(e,t){return o._get(e,0,t)}static getNumber(e,t){return this._get(e,1,t)}getNumber(e,t){return o._get(e,1,t)}static getBoolean(e,t){return this._get(e,2,t)}getBoolean(e,t){return o._get(e,2,t)}static getBigInt(e,t){return this._get(e,3,t)}getBigInt(e,t){return o._get(e,3,t)}static getSymbol(e,t){return this._get(e,4,t)}getSymbol(e,t){return o._get(e,4,t)}};export{o as PrimitiveMethods};
+import"node:path";import"node:url";import.meta.url;import{debugWarn as e}from"../infra/Debug.mjs";import{EnvapterBase as t}from"./EnvapterBase.mjs";import{EnvironmentMethods as n}from"./EnvironmentMethods.mjs";import{BuiltInConverters as r}from"../converters/BuiltInConverters.mjs";import{ValueConverter as i}from"../converters/ValueConverter.mjs";import{TemplateResolver as a}from"../engine/TemplateResolver.mjs";var o=class o extends n{static service=new o;static templateResolver=new a(o.service);static valueConverter=new i(o.service);isStrict(){return t.strict}static _get(t,n,i){let{key:a,value:o}=this.resolveKeyInput(t);if(this.treatAsMissing(o))return i!==void 0&&e(`${a} not found, using fallback ${String(i)}`),i;let s=o,c=this.templateResolver.resolveTemplate(a,String(s)),l;return l=n===1?r.number(c,i):n===2?r.boolean(c,i):n===3?r.bigint(c,i):n===4?r.symbol(c,i):r.string(c,i),l}static get(e,t){return this._get(e,0,t)}get(e,t){return o._get(e,0,t)}static getNumber(e,t){return this._get(e,1,t)}getNumber(e,t){return o._get(e,1,t)}static getBoolean(e,t){return this._get(e,2,t)}getBoolean(e,t){return o._get(e,2,t)}static getBigInt(e,t){return this._get(e,3,t)}getBigInt(e,t){return o._get(e,3,t)}static getSymbol(e,t){return this._get(e,4,t)}getSymbol(e,t){return o._get(e,4,t)}};export{o as PrimitiveMethods};
 //# sourceMappingURL=PrimitiveMethods.mjs.map

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

@@ -1 +1 @@
-{"version":3,"file":"PrimitiveMethods.mjs","names":[],"sources":["../../../src/core/PrimitiveMethods.ts"],"sourcesContent":["import { BuiltInConverters, ValueConverter } from '../converters';\nimport { debugWarn } from '../Debug';\nimport { TemplateResolver } from '../TemplateResolver';\nimport { EnvapterBase } from './EnvapterBase';\nimport { EnvironmentMethods } from './EnvironmentMethods';\n\nimport type { ConditionalReturn, EnvKeyInput } from '../types';\nimport type { EnvapterService } from '../types/Env';\n\n/**\n * @internal\n */\nenum Primitive {\n    String,\n    Number,\n    Boolean,\n    BigInt,\n    Symbol\n}\n\n/**\n * @internal\n */\nexport class PrimitiveMethods extends EnvironmentMethods implements EnvapterService {\n    private static readonly service = new PrimitiveMethods();\n    protected static readonly templateResolver: TemplateResolver = new TemplateResolver(PrimitiveMethods.service);\n    protected static readonly valueConverter: ValueConverter = new ValueConverter(PrimitiveMethods.service);\n\n    // Read `EnvapterBase.strict` directly: `PrimitiveMethods._strict` would resolve to the\n    // BaseClass default because a `Envapter.strict = true` write lands as an own-property\n    // on `Envapter`, which is a descendant of `PrimitiveMethods`, not an ancestor.\n    isStrict(): boolean {\n        return EnvapterBase.strict;\n    }\n\n    private static _get<EnvVarReturnType, DefaultType extends EnvVarReturnType | undefined = undefined>(\n        key: EnvKeyInput,\n        type: Primitive,\n        def?: DefaultType\n    ): ConditionalReturn<EnvVarReturnType, DefaultType> {\n        const { key: resolvedKey, value } = this.resolveKeyInput(key);\n        if (this.treatAsMissing(value)) {\n            if (def !== undefined) debugWarn(`${resolvedKey} not found, using fallback ${String(def)}`);\n            return def as ConditionalReturn<EnvVarReturnType, DefaultType>;\n        }\n        const rawVal = value as string | number | boolean | undefined;\n\n        const parsed = this.templateResolver.resolveTemplate(resolvedKey, String(rawVal));\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)\n            result = BuiltInConverters.boolean(parsed, def as boolean) as EnvVarReturnType;\n        else if (type === Primitive.BigInt)\n            result = BuiltInConverters.bigint(parsed, def as bigint) as EnvVarReturnType;\n        else if (type === Primitive.Symbol)\n            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\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 this._get(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 PrimitiveMethods._get(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 this._get(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 PrimitiveMethods._get(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 this._get(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 PrimitiveMethods._get(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 this._get(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 PrimitiveMethods._get(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 this._get(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 PrimitiveMethods._get(key, Primitive.Symbol, def);\n    }\n}\n"],"mappings":"iZAuBA,IAAa,EAAb,MAAa,UAAyB,CAA8C,CAChF,OAAwB,QAAU,IAAI,EACtC,OAA0B,iBAAqC,IAAI,EAAiB,EAAiB,OAAO,EAC5G,OAA0B,eAAiC,IAAI,EAAe,EAAiB,OAAO,EAKtG,UAAoB,CAChB,OAAO,EAAa,MACxB,CAEA,OAAe,KACX,EACA,EACA,EACgD,CAChD,GAAM,CAAE,IAAK,EAAa,SAAU,KAAK,gBAAgB,CAAG,EAC5D,GAAI,KAAK,eAAe,CAAK,EAEzB,OADI,IAAQ,IAAA,IAAW,EAAU,GAAG,EAAY,6BAA6B,OAAO,CAAG,GAAG,EACnF,EAEX,IAAM,EAAS,EAET,EAAS,KAAK,iBAAiB,gBAAgB,EAAa,OAAO,CAAM,CAAC,EAE5E,EAUJ,MATA,CAOK,EAPD,IAAA,EAAoC,EAAkB,OAAO,EAAQ,CAAa,EAC7E,IAAA,EACI,EAAkB,QAAQ,EAAQ,CAAc,EACpD,IAAA,EACI,EAAkB,OAAO,EAAQ,CAAa,EAClD,IAAA,EACI,EAAkB,OAAO,EAAQ,CAAa,EAC7C,EAAkB,OAAO,EAAQ,CAAa,EAErD,CACX,CAOA,OAAO,IACH,EACA,EACkC,CAClC,OAAO,KAAK,KAAK,EAAA,EAAuB,CAAG,CAC/C,CAKA,IACI,EACA,EACkC,CAClC,OAAO,EAAiB,KAAK,EAAA,EAAuB,CAAG,CAC3D,CAOA,OAAO,UACH,EACA,EACkC,CAClC,OAAO,KAAK,KAAK,EAAA,EAAuB,CAAG,CAC/C,CAKA,UACI,EACA,EACkC,CAClC,OAAO,EAAiB,KAAK,EAAA,EAAuB,CAAG,CAC3D,CAOA,OAAO,WACH,EACA,EACmC,CACnC,OAAO,KAAK,KAAK,EAAA,EAAwB,CAAG,CAChD,CAKA,WACI,EACA,EACmC,CACnC,OAAO,EAAiB,KAAK,EAAA,EAAwB,CAAG,CAC5D,CAOA,OAAO,UACH,EACA,EACkC,CAClC,OAAO,KAAK,KAAK,EAAA,EAAuB,CAAG,CAC/C,CAKA,UACI,EACA,EACkC,CAClC,OAAO,EAAiB,KAAK,EAAA,EAAuB,CAAG,CAC3D,CAOA,OAAO,UACH,EACA,EACkC,CAClC,OAAO,KAAK,KAAK,EAAA,EAAuB,CAAG,CAC/C,CAKA,UACI,EACA,EACkC,CAClC,OAAO,EAAiB,KAAK,EAAA,EAAuB,CAAG,CAC3D,CACJ"}
+{"version":3,"file":"PrimitiveMethods.mjs","names":[],"sources":["../../../src/core/PrimitiveMethods.ts"],"sourcesContent":["import { BuiltInConverters, ValueConverter } from '../converters';\nimport { EnvapterBase } from './EnvapterBase';\nimport { EnvironmentMethods } from './EnvironmentMethods';\nimport { TemplateResolver } from '../engine/TemplateResolver';\nimport { debugWarn } from '../infra/Debug';\n\nimport type { ConditionalReturn, EnvKeyInput } from '../types';\nimport type { EnvapterService } from '../types/Env';\n\n/**\n * @internal\n */\nenum Primitive {\n    String,\n    Number,\n    Boolean,\n    BigInt,\n    Symbol\n}\n\n/**\n * @internal\n */\nexport class PrimitiveMethods extends EnvironmentMethods implements EnvapterService {\n    private static readonly service = new PrimitiveMethods();\n    protected static readonly templateResolver: TemplateResolver = new TemplateResolver(PrimitiveMethods.service);\n    protected static readonly valueConverter: ValueConverter = new ValueConverter(PrimitiveMethods.service);\n\n    // Read `EnvapterBase.strict` directly: `PrimitiveMethods._strict` would resolve to the\n    // BaseClass default because a `Envapter.strict = true` write lands as an own-property\n    // on `Envapter`, which is a descendant of `PrimitiveMethods`, not an ancestor.\n    isStrict(): boolean {\n        return EnvapterBase.strict;\n    }\n\n    private static _get<EnvVarReturnType, DefaultType extends EnvVarReturnType | undefined = undefined>(\n        key: EnvKeyInput,\n        type: Primitive,\n        def?: DefaultType\n    ): ConditionalReturn<EnvVarReturnType, DefaultType> {\n        const { key: resolvedKey, value } = this.resolveKeyInput(key);\n        if (this.treatAsMissing(value)) {\n            if (def !== undefined) debugWarn(`${resolvedKey} not found, using fallback ${String(def)}`);\n            return def as ConditionalReturn<EnvVarReturnType, DefaultType>;\n        }\n        const rawVal = value as string | number | boolean | undefined;\n\n        const parsed = this.templateResolver.resolveTemplate(resolvedKey, String(rawVal));\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)\n            result = BuiltInConverters.boolean(parsed, def as boolean) as EnvVarReturnType;\n        else if (type === Primitive.BigInt)\n            result = BuiltInConverters.bigint(parsed, def as bigint) as EnvVarReturnType;\n        else if (type === Primitive.Symbol)\n            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\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 this._get(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 PrimitiveMethods._get(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 this._get(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 PrimitiveMethods._get(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 this._get(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 PrimitiveMethods._get(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 this._get(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 PrimitiveMethods._get(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 this._get(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 PrimitiveMethods._get(key, Primitive.Symbol, def);\n    }\n}\n"],"mappings":"8ZAuBA,IAAa,EAAb,MAAa,UAAyB,CAA8C,CAChF,OAAwB,QAAU,IAAI,EACtC,OAA0B,iBAAqC,IAAI,EAAiB,EAAiB,OAAO,EAC5G,OAA0B,eAAiC,IAAI,EAAe,EAAiB,OAAO,EAKtG,UAAoB,CAChB,OAAO,EAAa,MACxB,CAEA,OAAe,KACX,EACA,EACA,EACgD,CAChD,GAAM,CAAE,IAAK,EAAa,SAAU,KAAK,gBAAgB,CAAG,EAC5D,GAAI,KAAK,eAAe,CAAK,EAEzB,OADI,IAAQ,IAAA,IAAW,EAAU,GAAG,EAAY,6BAA6B,OAAO,CAAG,GAAG,EACnF,EAEX,IAAM,EAAS,EAET,EAAS,KAAK,iBAAiB,gBAAgB,EAAa,OAAO,CAAM,CAAC,EAE5E,EAUJ,MATA,CAOK,EAPD,IAAA,EAAoC,EAAkB,OAAO,EAAQ,CAAa,EAC7E,IAAA,EACI,EAAkB,QAAQ,EAAQ,CAAc,EACpD,IAAA,EACI,EAAkB,OAAO,EAAQ,CAAa,EAClD,IAAA,EACI,EAAkB,OAAO,EAAQ,CAAa,EAC7C,EAAkB,OAAO,EAAQ,CAAa,EAErD,CACX,CAOA,OAAO,IACH,EACA,EACkC,CAClC,OAAO,KAAK,KAAK,EAAA,EAAuB,CAAG,CAC/C,CAKA,IACI,EACA,EACkC,CAClC,OAAO,EAAiB,KAAK,EAAA,EAAuB,CAAG,CAC3D,CAOA,OAAO,UACH,EACA,EACkC,CAClC,OAAO,KAAK,KAAK,EAAA,EAAuB,CAAG,CAC/C,CAKA,UACI,EACA,EACkC,CAClC,OAAO,EAAiB,KAAK,EAAA,EAAuB,CAAG,CAC3D,CAOA,OAAO,WACH,EACA,EACmC,CACnC,OAAO,KAAK,KAAK,EAAA,EAAwB,CAAG,CAChD,CAKA,WACI,EACA,EACmC,CACnC,OAAO,EAAiB,KAAK,EAAA,EAAwB,CAAG,CAC5D,CAOA,OAAO,UACH,EACA,EACkC,CAClC,OAAO,KAAK,KAAK,EAAA,EAAuB,CAAG,CAC/C,CAKA,UACI,EACA,EACkC,CAClC,OAAO,EAAiB,KAAK,EAAA,EAAuB,CAAG,CAC3D,CAOA,OAAO,UACH,EACA,EACkC,CAClC,OAAO,KAAK,KAAK,EAAA,EAAuB,CAAG,CAC/C,CAKA,UACI,EACA,EACkC,CAClC,OAAO,EAAiB,KAAK,EAAA,EAAuB,CAAG,CAC3D,CACJ"}

package/dist/node/decorators/legacy/Envapt.cjs

@@ -0,0 +1,2 @@
+import"node:path";import"node:url";import.meta.url;const e=require("../parseEnvaptOptions.cjs"),t=require("./createPropertyDecorator.cjs");function n(n,r){return t.createPropertyDecorator(n,e.parseEnvaptOptions(r))}exports.Envapt=n;
+//# sourceMappingURL=Envapt.cjs.map

package/dist/node/decorators/legacy/Envapt.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Envapt.cjs","names":["createPropertyDecorator","parseEnvaptOptions"],"sources":["../../../../src/decorators/legacy/Envapt.ts"],"sourcesContent":["import { createPropertyDecorator } from './createPropertyDecorator';\nimport { parseEnvaptOptions } from '../parseEnvaptOptions';\n\nimport type { ArrayOf } from '../../converters';\nimport type { InferSchemaOutput, StandardSchemaV1 } from '../../infra/StandardSchema';\nimport type {\n    BuiltInConverter,\n    ConverterFunction,\n    EnvaptFieldDecorator,\n    EnvKeyInput,\n    InferConverterFallbackType,\n    InferConverterReturnType,\n    InferPrimitiveReturnType,\n    PrimitiveConstructor,\n    SchemaConstraint\n} from '../../types';\n\n/**\n * A custom converter function with a fallback (both required), or a fallback only.\n *\n * @param key - Environment variable name(s) to load\n * @param options - Configuration options\n * @public\n * @example\n * ```ts\n * class Config extends Envapter {\n *   \\@Envapt('API_KEY', {\n *     fallback: 'default-key',\n *     converter(raw, _fallback) {\n *       if (!raw || raw.trim() === '') throw new Error('API_KEY required');\n *       return raw.trim();\n *     }\n *   })\n *   static readonly apiKey: string;\n *\n *   \\@Envapt('LOG_FILE', { fallback: '/var/log/app.log' })\n *   static readonly logFile: string;\n *\n *   \\@Envapt('RETRY_POLICY', { fallback: { retries: 3, backoff: 'exponential' } })\n *   static readonly retryPolicy: unknown;\n * }\n * ```\n */\nexport function Envapt(\n    key: EnvKeyInput,\n    options: { fallback: undefined; converter?: undefined }\n): EnvaptFieldDecorator<string | undefined>;\nexport function Envapt<TFallback>(\n    key: EnvKeyInput,\n    options:\n        | { converter: (raw: string | undefined, fallback: TFallback) => TFallback; fallback: TFallback }\n        | { fallback: TFallback; converter?: undefined }\n): EnvaptFieldDecorator<TFallback>;\n\n/**\n * A custom converter function without a fallback. Omit `required` to return the converter's\n * output (possibly `undefined`), or pass `required: true` to throw `MissingEnvValue` on\n * missing or empty values.\n *\n * @param key - Environment variable name(s) to load\n * @param options - Configuration options\n * @public\n * @example\n * ```ts\n * class Config extends Envapter {\n *   \\@Envapt('FEATURE_FLAGS', { converter(raw) {\n *     return raw ? raw.split('|').map(s => s.trim()) : [];\n *   } })\n *   static readonly featureFlags: string[];\n *\n *   \\@Envapt('JWT_SECRET', {\n *     converter: (raw) => Buffer.from(raw ?? '', 'base64'),\n *     required: true\n *   })\n *   static readonly jwtSecret: Buffer;\n * }\n * ```\n */\nexport function Envapt<TReturnType>(\n    key: EnvKeyInput,\n    options:\n        | { converter: ConverterFunction<TReturnType>; required?: false }\n        | { converter: ConverterFunction<TReturnType>; required: true }\n): EnvaptFieldDecorator<TReturnType>;\n\n/**\n * A built-in or array converter with a fallback, or `required: true`. The fallback type tracks\n * the converter, so `Converters.Time` takes a number or time-string and `Converters.Url` takes\n * a `URL` instance.\n *\n * @param key - Environment variable name(s) to load\n * @param options - Configuration options\n * @public\n * @example\n * ```ts\n * import { Converters } from 'envapt';\n *\n * class Config extends Envapter {\n *   \\@Envapt('APP_PORT', { converter: Converters.Number, fallback: 3000 })\n *   static readonly port: number;\n *\n *   // the Url fallback is a URL instance, not a string\n *   \\@Envapt('APP_URL', { converter: Converters.Url, fallback: new URL('http://localhost:3000') })\n *   static readonly url: URL;\n *\n *   // prefers CANARY_URL when present, otherwise APP_URL\n *   \\@Envapt(['CANARY_URL', 'APP_URL'], { converter: Converters.Url })\n *   static readonly canaryUrl: URL | null;\n *\n *   // Time takes a number (milliseconds) or a time-string fallback (`<number><unit>`)\n *   \\@Envapt('REQUEST_TIMEOUT', { converter: Converters.Time, fallback: '10s' })\n *   static readonly requestTimeout: number;\n *\n *   \\@Envapt('ALLOWED_ORIGINS', {\n *     converter: Converters.array({ of: Converters.String }),\n *     fallback: ['https://example.com']\n *   })\n *   static readonly allowedOrigins: string[];\n *\n *   \\@Envapt('DATABASE_URL', { converter: Converters.Url, required: true })\n *   static readonly databaseUrl: URL;\n * }\n * ```\n */\nexport function Envapt<TConverter extends BuiltInConverter | ArrayOf>(\n    key: EnvKeyInput,\n    options:\n        | { converter: TConverter; fallback: InferConverterFallbackType<TConverter>; required?: false }\n        | { converter: TConverter; required: true }\n): EnvaptFieldDecorator<InferConverterReturnType<TConverter>>;\nexport function Envapt<TConverter extends BuiltInConverter | ArrayOf>(\n    key: EnvKeyInput,\n    options: { converter: TConverter; fallback: undefined; required?: false }\n): EnvaptFieldDecorator<InferConverterReturnType<TConverter> | undefined>;\nexport function Envapt<TConverter extends BuiltInConverter | ArrayOf>(\n    key: EnvKeyInput,\n    options: { converter: TConverter; required?: false }\n): EnvaptFieldDecorator<InferConverterReturnType<TConverter> | null>;\n\n/**\n * A primitive constructor (`Number`, `Boolean`) with an optional fallback.\n *\n * @param key - Environment variable name(s) to load\n * @param options - Configuration options\n * @public\n * @example\n * ```ts\n * class Config extends Envapter {\n *   \\@Envapt('MAX_CONNECTIONS', { converter: Number, fallback: 100 })\n *   static readonly maxConnections: number;\n *\n *   \\@Envapt('FEATURE_ENABLED', { converter: Boolean, fallback: false })\n *   static readonly featureEnabled: boolean;\n * }\n * ```\n */\nexport function Envapt<TConstructor extends PrimitiveConstructor>(\n    key: EnvKeyInput,\n    options:\n        | { converter: TConstructor; fallback: InferPrimitiveReturnType<TConstructor>; required?: false }\n        | { converter: TConstructor; required: true }\n): EnvaptFieldDecorator<InferPrimitiveReturnType<TConstructor>>;\nexport function Envapt<TConstructor extends PrimitiveConstructor>(\n    key: EnvKeyInput,\n    options: { converter: TConstructor; fallback: undefined; required?: false }\n): EnvaptFieldDecorator<InferPrimitiveReturnType<TConstructor> | undefined>;\nexport function Envapt<TConstructor extends PrimitiveConstructor>(\n    key: EnvKeyInput,\n    options: { converter: TConstructor; required?: false }\n): EnvaptFieldDecorator<InferPrimitiveReturnType<TConstructor> | null>;\n\n/**\n * Required, no converter (raw string). Throws `MissingEnvValue` on first access when the env\n * value is missing or empty after trimming, independent of the global `Envapter.strict` flag.\n * Pairing `required: true` with `fallback` matches no overload at compile time, and the runtime\n * Validator rejects dynamic objects that bypass the types.\n *\n * @param key - Environment variable name(s) to load\n * @param options - `{ required: true }`\n * @public\n * @example\n * ```ts\n * class Config extends Envapter {\n *   \\@Envapt('API_KEY', { required: true })\n *   static readonly apiKey: string;\n * }\n * ```\n */\nexport function Envapt(key: EnvKeyInput, options: { required: true }): EnvaptFieldDecorator<string>;\n\n/**\n * No-fallback form. The property resolves from env or `null`.\n *\n * @param key - Environment variable name(s) to load\n * @public\n * @example\n * ```ts\n * class Config extends Envapter {\n *   \\@Envapt('SIMPLE_VALUE')\n *   static readonly simple?: string | null;\n * }\n * ```\n */\nexport function Envapt(key: EnvKeyInput): EnvaptFieldDecorator<string | null>;\n\n/**\n * A Standard Schema v1 adapter (zod, valibot, arktype, hand-rolled). Synchronous schemas only,\n * so a Promise-returning `validate` throws `InvalidUserDefinedConfig` at runtime. Pairing\n * `schema` with `converter` matches no overload at compile time, and the runtime Validator\n * rejects dynamic objects that bypass the types.\n * @public\n */\nexport function Envapt<Schema extends StandardSchemaV1>(\n    key: EnvKeyInput,\n    options:\n        | { schema: SchemaConstraint<Schema>; fallback?: InferSchemaOutput<Schema>; required?: false }\n        | { schema: SchemaConstraint<Schema>; required: true }\n): EnvaptFieldDecorator<InferSchemaOutput<Schema>>;\n\n/**\n * Instance or static property decorator that loads and converts an environment variable.\n */\nexport function Envapt<TFallback = unknown>(key: EnvKeyInput, options?: unknown): EnvaptFieldDecorator<unknown> {\n    return createPropertyDecorator(key, parseEnvaptOptions<TFallback>(options)) as EnvaptFieldDecorator<unknown>;\n}\n"],"mappings":"2IA8NA,SAAgB,EAA4B,EAAkB,EAAkD,CAC5G,OAAOA,EAAAA,wBAAwB,EAAKC,EAAAA,mBAA8B,CAAO,CAAC,CAC9E"}

package/dist/node/decorators/{Envapt.d.cts → legacy/Envapt.d.cts}

@@ -1,13 +1,13 @@
-import { ArrayOf } from "../converters/Converters.cjs";
-import { BuiltInConverter, ConverterFunction, InferConverterFallbackType, InferPrimitiveReturnType, PrimitiveConstructor } from "../types/Conversion.cjs";
-import { InferSchemaOutput, StandardSchemaV1 } from "../StandardSchema.cjs";
-import { SchemaConstraint } from "../types/Schema.cjs";
-import { EnvKeyInput } from "../types/Env.cjs";
+import { ArrayOf } from "../../converters/Converters.cjs";
+import { BuiltInConverter, ConverterFunction, InferConverterFallbackType, InferConverterReturnType, InferPrimitiveReturnType, PrimitiveConstructor } from "../../types/Conversion.cjs";
+import { InferSchemaOutput, StandardSchemaV1 } from "../../infra/StandardSchema.cjs";
+import { SchemaConstraint } from "../../types/Schema.cjs";
+import { EnvKeyInput } from "../../types/Env.cjs";
+import { EnvaptFieldDecorator } from "../../types/Decorator.cjs";
 
-//#region src/decorators/Envapt.d.ts
+//#region src/decorators/legacy/Envapt.d.ts
 /**
- * Usage 1: Either a custom converter function + fallback (both required), OR a fallback
- * only (no converter).
+ * A custom converter function with a fallback (both required), or a fallback only.
  *
  * @param key - Environment variable name(s) to load
  * @param options - Configuration options
@@ -15,7 +15,6 @@ import { EnvKeyInput } from "../types/Env.cjs";
  * @example
  * ```ts
  * class Config extends Envapter {
- *   // Custom converter that validates a non-empty API key
  *   \@Envapt('API_KEY', {
  *     fallback: 'default-key',
  *     converter(raw, _fallback) {
@@ -25,30 +24,32 @@ import { EnvKeyInput } from "../types/Env.cjs";
  *   })
  *   static readonly apiKey: string;
  *
- *   // Fallback-only (no converter): string fallback
  *   \@Envapt('LOG_FILE', { fallback: '/var/log/app.log' })
  *   static readonly logFile: string;
  *
- *   // Fallback-only: arbitrary object fallback
  *   \@Envapt('RETRY_POLICY', { fallback: { retries: 3, backoff: 'exponential' } })
  *   static readonly retryPolicy: unknown;
  * }
  * ```
  */
+declare function Envapt(key: EnvKeyInput, options: {
+  fallback: undefined;
+  converter?: undefined;
+}): EnvaptFieldDecorator<string | undefined>;
 declare function Envapt<TFallback>(key: EnvKeyInput, options: {
   converter: (raw: string | undefined, fallback: TFallback) => TFallback;
   fallback: TFallback;
 } | {
   fallback: TFallback;
   converter?: undefined;
-}): PropertyDecorator;
+}): EnvaptFieldDecorator<TFallback>;
 /**
- * Usage 2: Custom converter function without fallback. Either omit `required` (returns the
- * converter's output, possibly `undefined`) or pass `required: true` to throw `MissingEnvValue`
- * on missing/empty values.
+ * A custom converter function without a fallback. Omit `required` to return the converter's
+ * output (possibly `undefined`), or pass `required: true` to throw `MissingEnvValue` on
+ * missing or empty values.
  *
  * @param key - Environment variable name(s) to load
- * @param options - Configuration options with custom converter only, with optional `required: true`
+ * @param options - Configuration options
  * @public
  * @example
  * ```ts
@@ -72,15 +73,11 @@ declare function Envapt<TReturnType>(key: EnvKeyInput, options: {
 } | {
   converter: ConverterFunction<TReturnType>;
   required: true;
-}): PropertyDecorator;
+}): EnvaptFieldDecorator<TReturnType>;
 /**
- * Usage 3: Built-in or array converter with optional fallback OR `required: true`.
- *
- * `InferConverterFallbackType` handles asymmetric cases: scalar `Converters.Time` accepts
- * `TimeFallback`, and `ArrayOf<'time'>` accepts `TimeFallback[]`. Every other converter
- * reduces to `InferConverterReturnType`. The two object-shape branches are mutually
- * exclusive: either provide a `fallback`, or pass `required: true` to throw
- * `MissingEnvValue` on missing/empty values.
+ * A built-in or array converter with a fallback, or `required: true`. The fallback type tracks
+ * the converter, so `Converters.Time` takes a number or time-string and `Converters.Url` takes
+ * a `URL` instance.
  *
  * @param key - Environment variable name(s) to load
  * @param options - Configuration options
@@ -90,23 +87,21 @@ declare function Envapt<TReturnType>(key: EnvKeyInput, options: {
  * import { Converters } from 'envapt';
  *
  * class Config extends Envapter {
- *   // Use built-in Number converter with a numeric fallback
  *   \@Envapt('APP_PORT', { converter: Converters.Number, fallback: 3000 })
  *   static readonly port: number;
  *
- *   // Url converter: the fallback is a URL instance, not a string
+ *   // the Url fallback is a URL instance, not a string
  *   \@Envapt('APP_URL', { converter: Converters.Url, fallback: new URL('http://localhost:3000') })
  *   static readonly url: URL;
  *
- *   // Prefer CANARY_URL when present, otherwise fall back to APP_URL
+ *   // prefers CANARY_URL when present, otherwise APP_URL
  *   \@Envapt(['CANARY_URL', 'APP_URL'], { converter: Converters.Url })
  *   static readonly canaryUrl: URL | null;
  *
- *   // `Converters.Time` accepts either a number (milliseconds) or a time-string fallback (`<number><unit>`).
+ *   // Time takes a number (milliseconds) or a time-string fallback (`<number><unit>`)
  *   \@Envapt('REQUEST_TIMEOUT', { converter: Converters.Time, fallback: '10s' })
  *   static readonly requestTimeout: number;
  *
- *   // Array converter: comma-separated list of origins -> string[]
  *   \@Envapt('ALLOWED_ORIGINS', {
  *     converter: Converters.array({ of: Converters.String }),
  *     fallback: ['https://example.com']
@@ -120,21 +115,29 @@ declare function Envapt<TReturnType>(key: EnvKeyInput, options: {
  */
 declare function Envapt<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, options: {
   converter: TConverter;
-  fallback?: InferConverterFallbackType<TConverter> | undefined;
+  fallback: InferConverterFallbackType<TConverter>;
   required?: false;
 } | {
   converter: TConverter;
   required: true;
-}): PropertyDecorator;
+}): EnvaptFieldDecorator<InferConverterReturnType<TConverter>>;
+declare function Envapt<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, options: {
+  converter: TConverter;
+  fallback: undefined;
+  required?: false;
+}): EnvaptFieldDecorator<InferConverterReturnType<TConverter> | undefined>;
+declare function Envapt<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, options: {
+  converter: TConverter;
+  required?: false;
+}): EnvaptFieldDecorator<InferConverterReturnType<TConverter> | null>;
 /**
- * Usage 4: Primitive constructor with optional fallback
+ * A primitive constructor (`Number`, `Boolean`) with an optional fallback.
  *
  * @param key - Environment variable name(s) to load
- * @param options - Configuration options with primitive constructor
+ * @param options - Configuration options
  * @public
  * @example
  * ```ts
- * // Use primitive constructors to coerce values
  * class Config extends Envapter {
  *   \@Envapt('MAX_CONNECTIONS', { converter: Number, fallback: 100 })
  *   static readonly maxConnections: number;
@@ -146,17 +149,26 @@ declare function Envapt<TConverter extends BuiltInConverter | ArrayOf>(key: EnvK
  */
 declare function Envapt<TConstructor extends PrimitiveConstructor>(key: EnvKeyInput, options: {
   converter: TConstructor;
-  fallback?: InferPrimitiveReturnType<TConstructor>;
+  fallback: InferPrimitiveReturnType<TConstructor>;
   required?: false;
 } | {
   converter: TConstructor;
   required: true;
-}): PropertyDecorator;
+}): EnvaptFieldDecorator<InferPrimitiveReturnType<TConstructor>>;
+declare function Envapt<TConstructor extends PrimitiveConstructor>(key: EnvKeyInput, options: {
+  converter: TConstructor;
+  fallback: undefined;
+  required?: false;
+}): EnvaptFieldDecorator<InferPrimitiveReturnType<TConstructor> | undefined>;
+declare function Envapt<TConstructor extends PrimitiveConstructor>(key: EnvKeyInput, options: {
+  converter: TConstructor;
+  required?: false;
+}): EnvaptFieldDecorator<InferPrimitiveReturnType<TConstructor> | null>;
 /**
- * Usage 5: Required, no converter (raw string). Throws `MissingEnvValue` on first access if
- * the env value is missing or empty (post-trim). Independent of global `Envapter.strict`.
- * Combining `required: true` with `fallback` fails to match any overload at compile time;
- * the runtime Validator catches dynamic objects that bypass the types.
+ * Required, no converter (raw string). Throws `MissingEnvValue` on first access when the env
+ * value is missing or empty after trimming, independent of the global `Envapter.strict` flag.
+ * Pairing `required: true` with `fallback` matches no overload at compile time, and the runtime
+ * Validator rejects dynamic objects that bypass the types.
  *
  * @param key - Environment variable name(s) to load
  * @param options - `{ required: true }`
@@ -171,7 +183,7 @@ declare function Envapt<TConstructor extends PrimitiveConstructor>(key: EnvKeyIn
  */
 declare function Envapt(key: EnvKeyInput, options: {
   required: true;
-}): PropertyDecorator;
+}): EnvaptFieldDecorator<string>;
 /**
  * No-fallback form. The property resolves from env or `null`.
  *
@@ -179,20 +191,18 @@ declare function Envapt(key: EnvKeyInput, options: {
  * @public
  * @example
  * ```ts
- * // Classic API: no fallback — property will resolve from env or be null
  * class Config extends Envapter {
  *   \@Envapt('SIMPLE_VALUE')
  *   static readonly simple?: string | null;
  * }
  * ```
  */
-declare function Envapt<_TReturnType = string | null>(key: EnvKeyInput): PropertyDecorator;
+declare function Envapt(key: EnvKeyInput): EnvaptFieldDecorator<string | null>;
 /**
- * Usage 6: Standard Schema v1 adapter (zod, valibot, arktype, hand-rolled). Synchronous
- * schemas only; a Promise-returning `validate` triggers a runtime
- * `InvalidUserDefinedConfig` throw. Combining `schema` with `converter` fails to match any
- * overload at compile time; the runtime Validator catches dynamic objects that bypass the
- * types.
+ * A Standard Schema v1 adapter (zod, valibot, arktype, hand-rolled). Synchronous schemas only,
+ * so a Promise-returning `validate` throws `InvalidUserDefinedConfig` at runtime. Pairing
+ * `schema` with `converter` matches no overload at compile time, and the runtime Validator
+ * rejects dynamic objects that bypass the types.
  * @public
  */
 declare function Envapt<Schema extends StandardSchemaV1>(key: EnvKeyInput, options: {
@@ -202,7 +212,7 @@ declare function Envapt<Schema extends StandardSchemaV1>(key: EnvKeyInput, optio
 } | {
   schema: SchemaConstraint<Schema>;
   required: true;
-}): PropertyDecorator;
+}): EnvaptFieldDecorator<InferSchemaOutput<Schema>>;
 //#endregion
 export { Envapt };
 //# sourceMappingURL=Envapt.d.cts.map