envapt 5.0.2 → 5.1.0

package/dist/core/EnvapterBase.d.cts

@@ -0,0 +1,105 @@
+import { DebugLevel } from "../Debug.cjs";
+import { EnvFileOptions } from "../Dotenv.cjs";
+import { EnvKeyInput } from "../types/Env.cjs";
+
+//#region src/core/EnvapterBase.d.ts
+/**
+ * Base class for environment variable management
+ * Handles configuration, caching, and basic environment loading
+ * @internal
+ */
+declare abstract class EnvapterBase {
+  protected static _envPaths: string[];
+  protected static _envPathsExplicitlySet: boolean;
+  protected static _baseDir: string | undefined;
+  protected static _userDefinedEnvFileOptions: EnvFileOptions;
+  protected static _strict: boolean;
+  protected static _syncProcessEnv: boolean;
+  protected static _dotenvAddedKeys: Set<string>;
+  /**
+   * Enable or disable strict mode. Default `false`. Setting refreshes the cache so
+   * previously-cached converted values get re-evaluated under the new rule.
+   */
+  static set strict(value: boolean);
+  static get strict(): boolean;
+  /**
+   * Set the debug log level. Defaults to `silent`. When unset, reads `ENVAPT_DEBUG` from
+   * `process.env` on first access; the setter overrides any env-var value. Output goes
+   * to stderr prefixed with `[envapt]`.
+   */
+  static set debug(level: DebugLevel);
+  static get debug(): DebugLevel;
+  /**
+   * Opt-in mirror of dotenv-loaded keys back to `process.env`. Default `false`.
+   *
+   * Only keys the loader actually wrote are mirrored, so collision behavior follows
+   * `envFileOptions.override`: with the default `false`, pre-existing `process.env` values
+   * are preserved; with `true`, the file value wins in both the cache and the mirror.
+   *
+   * Flipping `false → true` mirrors the existing tracked delta immediately (no cache
+   * refresh). Flipping `true → false` is one-way: previously mirrored keys remain in
+   * `process.env` until the process exits.
+   */
+  static set syncProcessEnv(value: boolean);
+  static get syncProcessEnv(): boolean;
+  protected static treatAsMissing(value: string | undefined): boolean;
+  /**
+   * Set custom .env file paths. Accepts either a single path or array of paths.
+   * Setting new paths clears the cache and reloads environment variables.
+   *
+   * When set, this takes absolute precedence. The dotenv-flow auto-cascade and any
+   * {@link configureProfiles} configuration are ignored.
+   */
+  static set envPaths(paths: string[] | string);
+  /**
+   * Get currently configured .env file paths
+   */
+  static get envPaths(): string[];
+  /**
+   * Set a base directory that relative `.env` paths resolve against instead of
+   * `process.cwd()`: the auto-cascade, {@link configureProfiles} paths, and relative
+   * `envPaths`. Absolute paths always bypass it. Pass a directory, or a module URL
+   * (`import.meta.url`, ESM) / `import.meta.dirname` / `__dirname` (CJS) to anchor
+   * resolution next to the calling file regardless of launch directory.
+   *
+   * Set this before `envPaths` so relative `envPaths` validate against the right directory.
+   * Unset (`undefined`) restores `process.cwd()` resolution.
+   */
+  static set baseDir(value: string | URL | undefined);
+  static get baseDir(): string | undefined;
+  private static normalizeBaseDir;
+  protected static resolveAgainstBase(candidate: string): string;
+  static set envFileOptions(config: EnvFileOptions);
+  /**
+   * Get current dotenv configuration options
+   */
+  static get envFileOptions(): EnvFileOptions;
+  protected static refreshCache(): void;
+  protected static mirrorToProcessEnv(): void;
+  /**
+   * Resolve the effective `.env` paths to load. Default implementation just returns the
+   * explicit `_envPaths` array; subclasses (`EnvironmentMethods`) override to layer in the
+   * dotenv-flow cascade and any {@link configureProfiles} overrides when `envPaths` was
+   * never explicitly set.
+   * @internal
+   */
+  protected static resolveEffectivePaths(): string[];
+  protected static resolveKeyInput(keyInput: EnvKeyInput): {
+    key: string;
+    value: string | undefined;
+  };
+  protected static get config(): Map<string, unknown>;
+  /**
+   * Eagerly load the `.env` cascade now instead of lazily on the first read. Idempotent: a no-op
+   * once the cache is built. Useful before mirroring to `process.env` (see {@link syncProcessEnv}),
+   * which is what the `envapt/config` side-effect entry does.
+   */
+  static load(): void;
+  /**
+   * Read an environment variable as its raw string, skipping parsing and conversion.
+   */
+  getRaw(key: EnvKeyInput): string | undefined;
+}
+//#endregion
+export { EnvapterBase };
+//# sourceMappingURL=EnvapterBase.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EnvapterBase.d.cts","names":[],"sources":["../../src/core/EnvapterBase.ts"],"mappings":";;;;;;;;;;uBAwBsB,YAAA;EAAA,iBACD,SAAA;EAAA,iBACA,sBAAA;EAAA,iBACA,QAAA;EAAA,iBACA,0BAAA,EAA4B,cAAA;EAAA,iBAC5B,OAAA;EAAA,iBACA,eAAA;EAAA,iBAEA,gBAAA,EAAkB,GAAA;EANlB;;;;EAAA,WAYN,MAAA,CAAO,KAAA;EAAA,WAOP,MAAA,CAAA;EAbM;;;;;EAAA,WAsBN,KAAA,CAAM,KAAA,EAAO,UAAA;EAAA,WAIb,KAAA,CAAA,GAAS,UAAA;EAJH;;;;;;;;;;;EAAA,WAmBN,cAAA,CAAe,KAAA;EAAA,WAQf,cAAA,CAAA;EAAA,iBAIM,cAAA,CAAe,KAAA;EA4CrB;;;;;;;EAAA,WA/BA,QAAA,CAAS,KAAA;EA0DS;;;EAAA,WA9ClB,QAAA,CAAA;EAiFM;;;;;;;;;;EAAA,WAnEN,OAAA,CAAQ,KAAA,WAAgB,GAAA;EAAA,WAKxB,OAAA,CAAA;EAAA,eAKI,gBAAA;EAAA,iBAOE,kBAAA,CAAmB,SAAA;EAAA,WAMzB,cAAA,CAAe,MAAA,EAAQ,cAAA;;;;aASvB,cAAA,CAAA,GAAkB,cAAA;EAAA,iBAIZ,YAAA,CAAA;EAAA,iBAOA,kBAAA,CAAA;;;;;;;;mBAmBA,qBAAA,CAAA;EAAA,iBAKA,eAAA,CAAgB,QAAA,EAAU,WAAA;IAAgB,GAAA;IAAa,KAAA;EAAA;EAAA,qBA0BnD,MAAA,CAAA,GAAU,GAAA;;;;;;SA+BxB,IAAA,CAAA;;;;EAOP,MAAA,CAAO,GAAA,EAAK,WAAA;AAAA"}

package/dist/core/EnvapterBase.d.mts

@@ -0,0 +1,105 @@
+import { DebugLevel } from "../Debug.mjs";
+import { EnvFileOptions } from "../Dotenv.mjs";
+import { EnvKeyInput } from "../types/Env.mjs";
+
+//#region src/core/EnvapterBase.d.ts
+/**
+ * Base class for environment variable management
+ * Handles configuration, caching, and basic environment loading
+ * @internal
+ */
+declare abstract class EnvapterBase {
+  protected static _envPaths: string[];
+  protected static _envPathsExplicitlySet: boolean;
+  protected static _baseDir: string | undefined;
+  protected static _userDefinedEnvFileOptions: EnvFileOptions;
+  protected static _strict: boolean;
+  protected static _syncProcessEnv: boolean;
+  protected static _dotenvAddedKeys: Set<string>;
+  /**
+   * Enable or disable strict mode. Default `false`. Setting refreshes the cache so
+   * previously-cached converted values get re-evaluated under the new rule.
+   */
+  static set strict(value: boolean);
+  static get strict(): boolean;
+  /**
+   * Set the debug log level. Defaults to `silent`. When unset, reads `ENVAPT_DEBUG` from
+   * `process.env` on first access; the setter overrides any env-var value. Output goes
+   * to stderr prefixed with `[envapt]`.
+   */
+  static set debug(level: DebugLevel);
+  static get debug(): DebugLevel;
+  /**
+   * Opt-in mirror of dotenv-loaded keys back to `process.env`. Default `false`.
+   *
+   * Only keys the loader actually wrote are mirrored, so collision behavior follows
+   * `envFileOptions.override`: with the default `false`, pre-existing `process.env` values
+   * are preserved; with `true`, the file value wins in both the cache and the mirror.
+   *
+   * Flipping `false → true` mirrors the existing tracked delta immediately (no cache
+   * refresh). Flipping `true → false` is one-way: previously mirrored keys remain in
+   * `process.env` until the process exits.
+   */
+  static set syncProcessEnv(value: boolean);
+  static get syncProcessEnv(): boolean;
+  protected static treatAsMissing(value: string | undefined): boolean;
+  /**
+   * Set custom .env file paths. Accepts either a single path or array of paths.
+   * Setting new paths clears the cache and reloads environment variables.
+   *
+   * When set, this takes absolute precedence. The dotenv-flow auto-cascade and any
+   * {@link configureProfiles} configuration are ignored.
+   */
+  static set envPaths(paths: string[] | string);
+  /**
+   * Get currently configured .env file paths
+   */
+  static get envPaths(): string[];
+  /**
+   * Set a base directory that relative `.env` paths resolve against instead of
+   * `process.cwd()`: the auto-cascade, {@link configureProfiles} paths, and relative
+   * `envPaths`. Absolute paths always bypass it. Pass a directory, or a module URL
+   * (`import.meta.url`, ESM) / `import.meta.dirname` / `__dirname` (CJS) to anchor
+   * resolution next to the calling file regardless of launch directory.
+   *
+   * Set this before `envPaths` so relative `envPaths` validate against the right directory.
+   * Unset (`undefined`) restores `process.cwd()` resolution.
+   */
+  static set baseDir(value: string | URL | undefined);
+  static get baseDir(): string | undefined;
+  private static normalizeBaseDir;
+  protected static resolveAgainstBase(candidate: string): string;
+  static set envFileOptions(config: EnvFileOptions);
+  /**
+   * Get current dotenv configuration options
+   */
+  static get envFileOptions(): EnvFileOptions;
+  protected static refreshCache(): void;
+  protected static mirrorToProcessEnv(): void;
+  /**
+   * Resolve the effective `.env` paths to load. Default implementation just returns the
+   * explicit `_envPaths` array; subclasses (`EnvironmentMethods`) override to layer in the
+   * dotenv-flow cascade and any {@link configureProfiles} overrides when `envPaths` was
+   * never explicitly set.
+   * @internal
+   */
+  protected static resolveEffectivePaths(): string[];
+  protected static resolveKeyInput(keyInput: EnvKeyInput): {
+    key: string;
+    value: string | undefined;
+  };
+  protected static get config(): Map<string, unknown>;
+  /**
+   * Eagerly load the `.env` cascade now instead of lazily on the first read. Idempotent: a no-op
+   * once the cache is built. Useful before mirroring to `process.env` (see {@link syncProcessEnv}),
+   * which is what the `envapt/config` side-effect entry does.
+   */
+  static load(): void;
+  /**
+   * Read an environment variable as its raw string, skipping parsing and conversion.
+   */
+  getRaw(key: EnvKeyInput): string | undefined;
+}
+//#endregion
+export { EnvapterBase };
+//# sourceMappingURL=EnvapterBase.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EnvapterBase.d.mts","names":[],"sources":["../../src/core/EnvapterBase.ts"],"mappings":";;;;;;;;;;uBAwBsB,YAAA;EAAA,iBACD,SAAA;EAAA,iBACA,sBAAA;EAAA,iBACA,QAAA;EAAA,iBACA,0BAAA,EAA4B,cAAA;EAAA,iBAC5B,OAAA;EAAA,iBACA,eAAA;EAAA,iBAEA,gBAAA,EAAkB,GAAA;EANlB;;;;EAAA,WAYN,MAAA,CAAO,KAAA;EAAA,WAOP,MAAA,CAAA;EAbM;;;;;EAAA,WAsBN,KAAA,CAAM,KAAA,EAAO,UAAA;EAAA,WAIb,KAAA,CAAA,GAAS,UAAA;EAJH;;;;;;;;;;;EAAA,WAmBN,cAAA,CAAe,KAAA;EAAA,WAQf,cAAA,CAAA;EAAA,iBAIM,cAAA,CAAe,KAAA;EA4CrB;;;;;;;EAAA,WA/BA,QAAA,CAAS,KAAA;EA0DS;;;EAAA,WA9ClB,QAAA,CAAA;EAiFM;;;;;;;;;;EAAA,WAnEN,OAAA,CAAQ,KAAA,WAAgB,GAAA;EAAA,WAKxB,OAAA,CAAA;EAAA,eAKI,gBAAA;EAAA,iBAOE,kBAAA,CAAmB,SAAA;EAAA,WAMzB,cAAA,CAAe,MAAA,EAAQ,cAAA;;;;aASvB,cAAA,CAAA,GAAkB,cAAA;EAAA,iBAIZ,YAAA,CAAA;EAAA,iBAOA,kBAAA,CAAA;;;;;;;;mBAmBA,qBAAA,CAAA;EAAA,iBAKA,eAAA,CAAgB,QAAA,EAAU,WAAA;IAAgB,GAAA;IAAa,KAAA;EAAA;EAAA,qBA0BnD,MAAA,CAAA,GAAU,GAAA;;;;;;SA+BxB,IAAA,CAAA;;;;EAOP,MAAA,CAAO,GAAA,EAAK,WAAA;AAAA"}

package/dist/core/EnvapterBase.mjs

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

package/dist/core/EnvapterBase.mjs.map

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

package/dist/core/EnvironmentMethods.cjs

@@ -0,0 +1,2 @@
+const e=require("../_virtual/_rolldown/runtime.cjs"),t=require("../Error.cjs"),n=require("./EnvapterBase.cjs");let r=require("node:fs");r=e.__toESM(r,1);let i=require("node:process");i=e.__toESM(i,1);let a=function(e){return e[e.Development=0]=`Development`,e[e.Staging=1]=`Staging`,e[e.Production=2]=`Production`,e}({});var o=class e extends n.EnvapterBase{static _environment;static _environmentExplicitlySet=!1;static _profiles;static determineEnvironment(e){let t=e??this.getRawValue(`ENVIRONMENT`,this.getRawValue(`ENV`,this.getRawValue(`NODE_ENV`,`development`)));typeof t==`string`?this._environment=t.toLowerCase()===`production`?2:+(t===`staging`):this._environment=t,e!==void 0&&(this._environmentExplicitlySet=!0)}static getRawValue(e,t){return this.config.get(e)||t}static get environment(){return this._environment===void 0&&this.determineEnvironment(),this._environment}static set environment(e){this.determineEnvironment(e)}get environment(){return e.environment}set environment(t){e.determineEnvironment(t)}static get isProduction(){return this.environment===2}get isProduction(){return e.environment===2}static get isStaging(){return this.environment===1}get isStaging(){return e.environment===1}static get isDevelopment(){return this.environment===0}get isDevelopment(){return e.environment===0}static refreshCache(){this._environmentExplicitlySet||(this._environment=void 0),super.refreshCache()}static configureProfiles(e){this._profiles=e,this.refreshCache()}static resetProfiles(){this._profiles=void 0,this._envPaths=[`.env`],this._envPathsExplicitlySet=!1,this._environmentExplicitlySet=!1,this._environment=void 0,this.refreshCache()}static getCascadeEnvironment(){if(this._environment!==void 0)return this._environment;let e=(i.default.env.ENVIRONMENT??i.default.env.ENV??i.default.env.NODE_ENV??`development`).toLowerCase();return e===`production`?2:+(e===`staging`)}static buildCascadePaths(e){let t=a[e].toLowerCase();return[`.env.${t}.local`,`.env.${t}`,`.env.local`,`.env`].map(e=>this.resolveAgainstBase(e)).filter(e=>r.default.existsSync(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 e=this.getCascadeEnvironment(),n=this._profiles?.[e],i=this.normalizeProfilePaths(n);if(i.length>0){let e=i.filter(e=>!r.default.existsSync(this.resolveAgainstBase(e)));if(e.length>0)throw new t.EnvaptError(303,`Environment file not found at path: ${e.join(`, `)}`)}let a=this._profiles?.useDefaults===!1?[]:this.buildCascadePaths(e);return[...i.map(e=>this.resolveAgainstBase(e)),...a]}};exports.Environment=a,exports.EnvironmentMethods=o;
+//# sourceMappingURL=EnvironmentMethods.cjs.map

package/dist/core/EnvironmentMethods.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnvironmentMethods.cjs","names":["EnvapterBase","process","fs","EnvaptError"],"sources":["../../src/core/EnvironmentMethods.ts"],"sourcesContent":["import fs from 'node:fs';\nimport process from 'node:process';\n\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}\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        const environment =\n            env ??\n            this.getRawValue('ENVIRONMENT', this.getRawValue('ENV', this.getRawValue('NODE_ENV', 'development')));\n\n        if (typeof environment === 'string') {\n            this._environment =\n                environment.toLowerCase() === 'production'\n                    ? Environment.Production\n                    : environment === 'staging'\n                      ? Environment.Staging\n                      : Environment.Development;\n        } else {\n            this._environment = environment;\n        }\n        if (env !== undefined) this._environmentExplicitlySet = true;\n    }\n\n    private static getRawValue(key: string, fallback: string): string {\n        return (this.config.get(key) as string) || fallback;\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    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     * Configure per-environment `.env` path overrides on top of the dotenv-flow auto-cascade.\n     *\n     * When set, each `Environment` key's `paths` are loaded at higher precedence than the\n     * cascade for that environment. Unspecified environments still use the cascade as-is.\n     * Set `useDefaults: false` to disable the cascade entirely (load only the configured paths).\n     *\n     * Setting an explicit `Envapter.envPaths` value at any point overrides this configuration.\n     *\n     * @example\n     * ```ts\n     * Envapter.configureProfiles({\n     *   [Environment.Staging]: { paths: 'config/staging.env' },\n     *   [Environment.Production]: { paths: ['config/prod.env', 'secrets/prod.env'] }\n     * });\n     * ```\n     */\n    static configureProfiles(config: ProfilesConfig): void {\n        this._profiles = config;\n        this.refreshCache();\n    }\n\n    /**\n     * Reset all path-resolution configuration to defaults: clears any prior\n     * {@link configureProfiles} call AND any explicit `Envapter.envPaths` assignment.\n     * Returns the resolver to the pure dotenv-flow cascade.\n     */\n    static resetProfiles(): void {\n        this._profiles = undefined;\n        this._envPaths = ['.env'];\n        this._envPathsExplicitlySet = false;\n        // Also clear the explicit-env flag so the next refresh re-determines env from\n        // process.env / loaded files. resetProfiles is a \"back to defaults\" call.\n        // Any user-set environment is wiped along with paths and profiles.\n        this._environmentExplicitlySet = false;\n        this._environment = undefined;\n        this.refreshCache();\n    }\n\n    /**\n     * Determine the current environment for cascade-file selection by reading `process.env`\n     * directly. Bypassing `this.config` to avoid a circular dependency (cascade selection\n     * happens before `.env` files are loaded). The post-load `Envapter.environment` value\n     * may differ if a loaded `.env` file declares its own `ENVIRONMENT`/`ENV`/`NODE_ENV`.\n     * @internal\n     */\n    protected static getCascadeEnvironment(): Environment {\n        if (this._environment !== undefined) return this._environment;\n\n        const raw = process.env.ENVIRONMENT ?? process.env.ENV ?? process.env.NODE_ENV ?? 'development';\n        const lower = raw.toLowerCase();\n        if (lower === 'production') return Environment.Production;\n        if (lower === 'staging') return Environment.Staging;\n        return 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) => fs.existsSync(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     * {@link 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) => !fs.existsSync(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/core/EnvironmentMethods.d.cts

@@ -0,0 +1,132 @@
+import { EnvapterBase } from "./EnvapterBase.cjs";
+import { ProfilesConfig } from "../types/Options.cjs";
+
+//#region src/core/EnvironmentMethods.d.ts
+/**
+ * Environment types supported by Envapter
+ * @public
+ */
+declare enum Environment {
+  Development = 0,
+  Staging = 1,
+  Production = 2
+}
+/**
+ * Mixin for environment detection and checking methods
+ * @internal
+ */
+declare class EnvironmentMethods extends EnvapterBase {
+  protected static _environment: Environment | undefined;
+  protected static _environmentExplicitlySet: boolean;
+  protected static _profiles: ProfilesConfig | undefined;
+  protected static determineEnvironment(env?: string | Environment): void;
+  private static getRawValue;
+  /**
+   * Get the current application environment
+   */
+  static get environment(): Environment;
+  /**
+   * Set the application environment. Accepts either Environment enum or string value.
+   */
+  static set environment(env: string | Environment);
+  /**
+   * @see {@link EnvironmentMethods.environment}
+   */
+  get environment(): Environment;
+  /**
+   * @see {@link EnvironmentMethods.environment}
+   */
+  set environment(env: string | Environment);
+  /**
+   * Check if the current environment is production
+   */
+  static get isProduction(): boolean;
+  /**
+   * @see {@link EnvironmentMethods.isProduction}
+   */
+  get isProduction(): boolean;
+  /**
+   * Check if the current environment is staging
+   */
+  static get isStaging(): boolean;
+  /**
+   * @see {@link EnvironmentMethods.isStaging}
+   */
+  get isStaging(): boolean;
+  /**
+   * Check if the current environment is development
+   */
+  static get isDevelopment(): boolean;
+  /**
+   * @see {@link EnvironmentMethods.isDevelopment}
+   */
+  get isDevelopment(): boolean;
+  protected static refreshCache(): void;
+  /**
+   * Configure per-environment `.env` path overrides on top of the dotenv-flow auto-cascade.
+   *
+   * When set, each `Environment` key's `paths` are loaded at higher precedence than the
+   * cascade for that environment. Unspecified environments still use the cascade as-is.
+   * Set `useDefaults: false` to disable the cascade entirely (load only the configured paths).
+   *
+   * Setting an explicit `Envapter.envPaths` value at any point overrides this configuration.
+   *
+   * @example
+   * ```ts
+   * Envapter.configureProfiles({
+   *   [Environment.Staging]: { paths: 'config/staging.env' },
+   *   [Environment.Production]: { paths: ['config/prod.env', 'secrets/prod.env'] }
+   * });
+   * ```
+   */
+  static configureProfiles(config: ProfilesConfig): void;
+  /**
+   * Reset all path-resolution configuration to defaults: clears any prior
+   * {@link configureProfiles} call AND any explicit `Envapter.envPaths` assignment.
+   * Returns the resolver to the pure dotenv-flow cascade.
+   */
+  static resetProfiles(): void;
+  /**
+   * Determine the current environment for cascade-file selection by reading `process.env`
+   * directly. Bypassing `this.config` to avoid a circular dependency (cascade selection
+   * happens before `.env` files are loaded). The post-load `Envapter.environment` value
+   * may differ if a loaded `.env` file declares its own `ENVIRONMENT`/`ENV`/`NODE_ENV`.
+   * @internal
+   */
+  protected static getCascadeEnvironment(): Environment;
+  /**
+   * Build the dotenv-flow cascade for a given environment, in dotenv first-wins precedence
+   * order (highest precedence first). Missing files are silently filtered.
+   *
+   * Precedence is **most-specific-wins** (matches Vite / Astro / Vocs):
+   *   `.env.${env}.local` \> `.env.${env}` \> `.env.local` \> `.env`
+   *
+   * This differs from dotenv-flow / Next.js convention which puts `.env.local` above
+   * `.env.${env}`. We chose the most-specific-wins order so committed env-specific files
+   * (`.env.production`) are authoritative for that environment regardless of whether a
+   * stray `.env.local` is present.
+   * @internal
+   */
+  protected static buildCascadePaths(env: Environment): string[];
+  private static normalizeProfilePaths;
+  /**
+   * Override the base implementation to layer the dotenv-flow cascade + any
+   * {@link configureProfiles} overrides on top of `_envPaths` when the user has NOT
+   * explicitly set `envPaths`.
+   *
+   * Precedence (passed to dotenv with first-wins semantics):
+   *   1. profile-configured paths for the current env (if any)
+   *   2. `.env.${env}.local`
+   *   3. `.env.${env}`
+   *   4. `.env.local`
+   *   5. `.env`
+   *
+   * If `useDefaults: false` is set on the profiles config, only (1) is loaded — no cascade.
+   * If `envPaths` was explicitly set, only `envPaths` is loaded (everything else ignored).
+   * @internal
+   */
+  protected static resolveEffectivePaths(): string[];
+}
+//#endregion
+export { Environment, EnvironmentMethods };
+//# sourceMappingURL=EnvironmentMethods.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EnvironmentMethods.d.cts","names":[],"sources":["../../src/core/EnvironmentMethods.ts"],"mappings":";;;;;;AAYA;;aAAY,WAAA;EACR,WAAA;EACA,OAAA;EACA,UAAA;AAAA;;AAAU;AAOd;;cAAa,kBAAA,SAA2B,YAAA;EAAA,iBACnB,YAAA,EAAc,WAAA;EAAA,iBACd,yBAAA;EAAA,iBACA,SAAA,EAAW,cAAA;EAAA,iBAEX,oBAAA,CAAqB,GAAA,YAAe,WAAA;EAAA,eAkBtC,WAAA;EAwBI;;;EAAA,WAjBR,WAAA,CAAA,GAAe,WAAA;EAoJc;;;EAAA,WA1I7B,WAAA,CAAY,GAAA,WAAc,WAAA;EAxCD;;;EAAA,IA+ChC,WAAA,CAAA,GAAe,WAAA;EA5CF;;;EAAA,IAmDb,WAAA,CAAY,GAAA,WAAc,WAAA;EAjDQ;;;EAAA,WAwD3B,YAAA,CAAA;EArBA;;;EAAA,IA4BP,YAAA,CAAA;EArBe;;;EAAA,WA4BR,SAAA,CAAA;EAdA;;;EAAA,IAqBP,SAAA,CAAA;EAOO;;;EAAA,WAAA,aAAA,CAAA;EAqCsB;;;EAAA,IA9B7B,aAAA,CAAA;EAAA,iBAIsB,YAAA,CAAA;EA8ET;;;;;;AA4B8B;;;;;;;;;;;EA5B9B,OApDV,iBAAA,CAAkB,MAAA,EAAQ,cAAA;;;;;;SAU1B,aAAA,CAAA;;;;;;;;mBAmBU,qBAAA,CAAA,GAAyB,WAAA;;;;;;;;;;;;;;mBAuBzB,iBAAA,CAAkB,GAAA,EAAK,WAAA;EAAA,eAOzB,qBAAA;;;;;;;;;;;;;;;;;mBAqBW,qBAAA,CAAA;AAAA"}

package/dist/core/EnvironmentMethods.d.mts

@@ -0,0 +1,132 @@
+import { EnvapterBase } from "./EnvapterBase.mjs";
+import { ProfilesConfig } from "../types/Options.mjs";
+
+//#region src/core/EnvironmentMethods.d.ts
+/**
+ * Environment types supported by Envapter
+ * @public
+ */
+declare enum Environment {
+  Development = 0,
+  Staging = 1,
+  Production = 2
+}
+/**
+ * Mixin for environment detection and checking methods
+ * @internal
+ */
+declare class EnvironmentMethods extends EnvapterBase {
+  protected static _environment: Environment | undefined;
+  protected static _environmentExplicitlySet: boolean;
+  protected static _profiles: ProfilesConfig | undefined;
+  protected static determineEnvironment(env?: string | Environment): void;
+  private static getRawValue;
+  /**
+   * Get the current application environment
+   */
+  static get environment(): Environment;
+  /**
+   * Set the application environment. Accepts either Environment enum or string value.
+   */
+  static set environment(env: string | Environment);
+  /**
+   * @see {@link EnvironmentMethods.environment}
+   */
+  get environment(): Environment;
+  /**
+   * @see {@link EnvironmentMethods.environment}
+   */
+  set environment(env: string | Environment);
+  /**
+   * Check if the current environment is production
+   */
+  static get isProduction(): boolean;
+  /**
+   * @see {@link EnvironmentMethods.isProduction}
+   */
+  get isProduction(): boolean;
+  /**
+   * Check if the current environment is staging
+   */
+  static get isStaging(): boolean;
+  /**
+   * @see {@link EnvironmentMethods.isStaging}
+   */
+  get isStaging(): boolean;
+  /**
+   * Check if the current environment is development
+   */
+  static get isDevelopment(): boolean;
+  /**
+   * @see {@link EnvironmentMethods.isDevelopment}
+   */
+  get isDevelopment(): boolean;
+  protected static refreshCache(): void;
+  /**
+   * Configure per-environment `.env` path overrides on top of the dotenv-flow auto-cascade.
+   *
+   * When set, each `Environment` key's `paths` are loaded at higher precedence than the
+   * cascade for that environment. Unspecified environments still use the cascade as-is.
+   * Set `useDefaults: false` to disable the cascade entirely (load only the configured paths).
+   *
+   * Setting an explicit `Envapter.envPaths` value at any point overrides this configuration.
+   *
+   * @example
+   * ```ts
+   * Envapter.configureProfiles({
+   *   [Environment.Staging]: { paths: 'config/staging.env' },
+   *   [Environment.Production]: { paths: ['config/prod.env', 'secrets/prod.env'] }
+   * });
+   * ```
+   */
+  static configureProfiles(config: ProfilesConfig): void;
+  /**
+   * Reset all path-resolution configuration to defaults: clears any prior
+   * {@link configureProfiles} call AND any explicit `Envapter.envPaths` assignment.
+   * Returns the resolver to the pure dotenv-flow cascade.
+   */
+  static resetProfiles(): void;
+  /**
+   * Determine the current environment for cascade-file selection by reading `process.env`
+   * directly. Bypassing `this.config` to avoid a circular dependency (cascade selection
+   * happens before `.env` files are loaded). The post-load `Envapter.environment` value
+   * may differ if a loaded `.env` file declares its own `ENVIRONMENT`/`ENV`/`NODE_ENV`.
+   * @internal
+   */
+  protected static getCascadeEnvironment(): Environment;
+  /**
+   * Build the dotenv-flow cascade for a given environment, in dotenv first-wins precedence
+   * order (highest precedence first). Missing files are silently filtered.
+   *
+   * Precedence is **most-specific-wins** (matches Vite / Astro / Vocs):
+   *   `.env.${env}.local` \> `.env.${env}` \> `.env.local` \> `.env`
+   *
+   * This differs from dotenv-flow / Next.js convention which puts `.env.local` above
+   * `.env.${env}`. We chose the most-specific-wins order so committed env-specific files
+   * (`.env.production`) are authoritative for that environment regardless of whether a
+   * stray `.env.local` is present.
+   * @internal
+   */
+  protected static buildCascadePaths(env: Environment): string[];
+  private static normalizeProfilePaths;
+  /**
+   * Override the base implementation to layer the dotenv-flow cascade + any
+   * {@link configureProfiles} overrides on top of `_envPaths` when the user has NOT
+   * explicitly set `envPaths`.
+   *
+   * Precedence (passed to dotenv with first-wins semantics):
+   *   1. profile-configured paths for the current env (if any)
+   *   2. `.env.${env}.local`
+   *   3. `.env.${env}`
+   *   4. `.env.local`
+   *   5. `.env`
+   *
+   * If `useDefaults: false` is set on the profiles config, only (1) is loaded — no cascade.
+   * If `envPaths` was explicitly set, only `envPaths` is loaded (everything else ignored).
+   * @internal
+   */
+  protected static resolveEffectivePaths(): string[];
+}
+//#endregion
+export { Environment, EnvironmentMethods };
+//# sourceMappingURL=EnvironmentMethods.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EnvironmentMethods.d.mts","names":[],"sources":["../../src/core/EnvironmentMethods.ts"],"mappings":";;;;;;AAYA;;aAAY,WAAA;EACR,WAAA;EACA,OAAA;EACA,UAAA;AAAA;;AAAU;AAOd;;cAAa,kBAAA,SAA2B,YAAA;EAAA,iBACnB,YAAA,EAAc,WAAA;EAAA,iBACd,yBAAA;EAAA,iBACA,SAAA,EAAW,cAAA;EAAA,iBAEX,oBAAA,CAAqB,GAAA,YAAe,WAAA;EAAA,eAkBtC,WAAA;EAwBI;;;EAAA,WAjBR,WAAA,CAAA,GAAe,WAAA;EAoJc;;;EAAA,WA1I7B,WAAA,CAAY,GAAA,WAAc,WAAA;EAxCD;;;EAAA,IA+ChC,WAAA,CAAA,GAAe,WAAA;EA5CF;;;EAAA,IAmDb,WAAA,CAAY,GAAA,WAAc,WAAA;EAjDQ;;;EAAA,WAwD3B,YAAA,CAAA;EArBA;;;EAAA,IA4BP,YAAA,CAAA;EArBe;;;EAAA,WA4BR,SAAA,CAAA;EAdA;;;EAAA,IAqBP,SAAA,CAAA;EAOO;;;EAAA,WAAA,aAAA,CAAA;EAqCsB;;;EAAA,IA9B7B,aAAA,CAAA;EAAA,iBAIsB,YAAA,CAAA;EA8ET;;;;;;AA4B8B;;;;;;;;;;;EA5B9B,OApDV,iBAAA,CAAkB,MAAA,EAAQ,cAAA;;;;;;SAU1B,aAAA,CAAA;;;;;;;;mBAmBU,qBAAA,CAAA,GAAyB,WAAA;;;;;;;;;;;;;;mBAuBzB,iBAAA,CAAkB,GAAA,EAAK,WAAA;EAAA,eAOzB,qBAAA;;;;;;;;;;;;;;;;;mBAqBW,qBAAA,CAAA;AAAA"}

package/dist/core/EnvironmentMethods.mjs

@@ -0,0 +1,2 @@
+import{EnvaptError as e}from"../Error.mjs";import{EnvapterBase as t}from"./EnvapterBase.mjs";import n from"node:fs";import r from"node:process";let i=function(e){return e[e.Development=0]=`Development`,e[e.Staging=1]=`Staging`,e[e.Production=2]=`Production`,e}({});var a=class a extends t{static _environment;static _environmentExplicitlySet=!1;static _profiles;static determineEnvironment(e){let t=e??this.getRawValue(`ENVIRONMENT`,this.getRawValue(`ENV`,this.getRawValue(`NODE_ENV`,`development`)));typeof t==`string`?this._environment=t.toLowerCase()===`production`?2:+(t===`staging`):this._environment=t,e!==void 0&&(this._environmentExplicitlySet=!0)}static getRawValue(e,t){return this.config.get(e)||t}static get environment(){return this._environment===void 0&&this.determineEnvironment(),this._environment}static set environment(e){this.determineEnvironment(e)}get environment(){return a.environment}set environment(e){a.determineEnvironment(e)}static get isProduction(){return this.environment===2}get isProduction(){return a.environment===2}static get isStaging(){return this.environment===1}get isStaging(){return a.environment===1}static get isDevelopment(){return this.environment===0}get isDevelopment(){return a.environment===0}static refreshCache(){this._environmentExplicitlySet||(this._environment=void 0),super.refreshCache()}static configureProfiles(e){this._profiles=e,this.refreshCache()}static resetProfiles(){this._profiles=void 0,this._envPaths=[`.env`],this._envPathsExplicitlySet=!1,this._environmentExplicitlySet=!1,this._environment=void 0,this.refreshCache()}static getCascadeEnvironment(){if(this._environment!==void 0)return this._environment;let e=(r.env.ENVIRONMENT??r.env.ENV??r.env.NODE_ENV??`development`).toLowerCase();return e===`production`?2:+(e===`staging`)}static buildCascadePaths(e){let t=i[e].toLowerCase();return[`.env.${t}.local`,`.env.${t}`,`.env.local`,`.env`].map(e=>this.resolveAgainstBase(e)).filter(e=>n.existsSync(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(),r=this._profiles?.[t],i=this.normalizeProfilePaths(r);if(i.length>0){let t=i.filter(e=>!n.existsSync(this.resolveAgainstBase(e)));if(t.length>0)throw new e(303,`Environment file not found at path: ${t.join(`, `)}`)}let a=this._profiles?.useDefaults===!1?[]:this.buildCascadePaths(t);return[...i.map(e=>this.resolveAgainstBase(e)),...a]}};export{i as Environment,a as EnvironmentMethods};
+//# sourceMappingURL=EnvironmentMethods.mjs.map

package/dist/core/EnvironmentMethods.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnvironmentMethods.mjs","names":[],"sources":["../../src/core/EnvironmentMethods.ts"],"sourcesContent":["import fs from 'node:fs';\nimport process from 'node:process';\n\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}\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        const environment =\n            env ??\n            this.getRawValue('ENVIRONMENT', this.getRawValue('ENV', this.getRawValue('NODE_ENV', 'development')));\n\n        if (typeof environment === 'string') {\n            this._environment =\n                environment.toLowerCase() === 'production'\n                    ? Environment.Production\n                    : environment === 'staging'\n                      ? Environment.Staging\n                      : Environment.Development;\n        } else {\n            this._environment = environment;\n        }\n        if (env !== undefined) this._environmentExplicitlySet = true;\n    }\n\n    private static getRawValue(key: string, fallback: string): string {\n        return (this.config.get(key) as string) || fallback;\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    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     * Configure per-environment `.env` path overrides on top of the dotenv-flow auto-cascade.\n     *\n     * When set, each `Environment` key's `paths` are loaded at higher precedence than the\n     * cascade for that environment. Unspecified environments still use the cascade as-is.\n     * Set `useDefaults: false` to disable the cascade entirely (load only the configured paths).\n     *\n     * Setting an explicit `Envapter.envPaths` value at any point overrides this configuration.\n     *\n     * @example\n     * ```ts\n     * Envapter.configureProfiles({\n     *   [Environment.Staging]: { paths: 'config/staging.env' },\n     *   [Environment.Production]: { paths: ['config/prod.env', 'secrets/prod.env'] }\n     * });\n     * ```\n     */\n    static configureProfiles(config: ProfilesConfig): void {\n        this._profiles = config;\n        this.refreshCache();\n    }\n\n    /**\n     * Reset all path-resolution configuration to defaults: clears any prior\n     * {@link configureProfiles} call AND any explicit `Envapter.envPaths` assignment.\n     * Returns the resolver to the pure dotenv-flow cascade.\n     */\n    static resetProfiles(): void {\n        this._profiles = undefined;\n        this._envPaths = ['.env'];\n        this._envPathsExplicitlySet = false;\n        // Also clear the explicit-env flag so the next refresh re-determines env from\n        // process.env / loaded files. resetProfiles is a \"back to defaults\" call.\n        // Any user-set environment is wiped along with paths and profiles.\n        this._environmentExplicitlySet = false;\n        this._environment = undefined;\n        this.refreshCache();\n    }\n\n    /**\n     * Determine the current environment for cascade-file selection by reading `process.env`\n     * directly. Bypassing `this.config` to avoid a circular dependency (cascade selection\n     * happens before `.env` files are loaded). The post-load `Envapter.environment` value\n     * may differ if a loaded `.env` file declares its own `ENVIRONMENT`/`ENV`/`NODE_ENV`.\n     * @internal\n     */\n    protected static getCascadeEnvironment(): Environment {\n        if (this._environment !== undefined) return this._environment;\n\n        const raw = process.env.ENVIRONMENT ?? process.env.ENV ?? process.env.NODE_ENV ?? 'development';\n        const lower = raw.toLowerCase();\n        if (lower === 'production') return Environment.Production;\n        if (lower === 'staging') return Environment.Staging;\n        return 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) => fs.existsSync(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     * {@link 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) => !fs.existsSync(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/core/PrimitiveMethods.cjs

@@ -0,0 +1,2 @@
+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;
+//# sourceMappingURL=PrimitiveMethods.cjs.map

package/dist/core/PrimitiveMethods.cjs.map

@@ -0,0 +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 as ConditionalReturn<EnvVarReturnType, DefaultType>;\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":"0OAuBA,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"}