envapt 5.1.0 → 5.2.0-next.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # envapt
 
+## 5.2.0-next.0
+
+### Minor Changes
+
+- e506a6d: `Envapter` now detects the test environment and reads Vite's `MODE`.
+    - `Environment.Test` and `Envapter.isTest` are added. `NODE_ENV=test` (and Vite's `MODE=test`) now resolve to `Environment.Test`, where they previously fell through to `Development`. As a result, `isDevelopment` is no longer `true` under a test runner that sets `NODE_ENV=test`.
+    - `MODE` joins the detection chain, after `ENVIRONMENT`, `ENV`, and `NODE_ENV`. Vite-family browser builds expose `import.meta.env.MODE` but none of the others, so `new ManualEnvSource(import.meta.env)` now sets the environment from `MODE`.
+    - Environment names match case-insensitively. Previously `staging` was matched case-sensitively, so `STAGING` or `Staging` fell through to `Development`; `production` was already case-insensitive.
+    - When no environment key is set, or its value is unrecognized, detection defaults to `Development` and emits a debug warning (visible with `Envapter.debug = 'warn'`).
+
+- e506a6d: envapt now runs on the browser and Cloudflare Workers, not only Node. The engine reads variables through a pluggable `EnvSource` instead of reading `process.env` directly, so the same `Envapter` and `@Envapt` API works against an injected object or a Workers binding.
+
+    `Envapter.useSource(source)` binds the source; the bound source then backs every read, the `.env` cascade, and `Envapter.syncProcessEnv`. Built-in sources, all exported from `envapt`:
+    - `NodeEnvSource`: a `process.env` snapshot plus the `.env` cascade. Bound automatically on Node, Bun, and Deno, so you do not call `useSource` yourself.
+    - `WorkerEnvSource`: reads a Cloudflare Workers `env` binding. Non-string bindings are JSON-stringified so the converters still apply.
+    - `ManualEnvSource`: reads any object you pass in, snapshotted at construction, with non-string values JSON-stringified like `WorkerEnvSource`. Pass `import.meta.env` or a bundler-injected object directly on the browser, or a plain object in tests.
+
+    ```ts
+    import { Envapter, ManualEnvSource } from 'envapt';
+
+    Envapter.useSource(new ManualEnvSource({ PORT: '3000', FLAG: 'true' }));
+    Envapter.getNumber('PORT'); // 3000
+    ```
+
+    The core imports no `node:*` module: `node:fs`, `node:path`, `node:process`, and `node:url` are confined to `NodeEnvSource`. envapt ships a build per runtime, so a Workers or browser bundle pulls in no Node built-ins, and workerd needs no `nodejs_compat` flag. Bare `envapt` resolves the right build through the `exports` conditions, and the dedicated `envapt/workerd` and `envapt/browser` entries add the matching types, which omit the file-only APIs so a stray call is a compile error rather than a runtime `FileApiUnsupported`.
+
+    Two new `EnvaptErrorCodes` replace silent no-ops with a thrown error:
+    - `NoSourceBound` (307): thrown on the first read when no source is bound.
+    - `FileApiUnsupported` (306): thrown when `envPaths`, `baseDir`, or `configureProfiles` is called on a source without a filesystem.
+
+    `EnvSource` is a union of `BareEnvSource` (no filesystem) and `FileEnvSource` (which requires `readFile`, `resolvePath`, `normalizeBaseDir`, and `writeVars` together), so a custom source has either the full file API or none of it.
+
+    On Node, the `.env` cascade now loads when envapt is first imported rather than on the first variable read.
+
+### Patch Changes
+
+- e506a6d: `Converters.Time` string fallbacks now accept decimals, matching raw env values.
+
+    A fallback like `'1.5h'` previously threw `MalformedTimeFallback` even though the `TimeFallback` type (`` `${number}${TimeUnit}` ``) accepts it at compile time. Raw env values already allowed decimals, so the restriction only applied to fallbacks, which was inconsistent. A string fallback still requires an explicit unit (a unitless number is a number fallback), but `'1.5h'` now resolves to `5400000`.
+
+## 5.1.1
+
+### Patch Changes
+
+- Embed the README into the published npm manifest so it renders on the package page. pnpm leaves the README out of the manifest by default, which left npmjs.com showing no README on every prior release.
+
 ## 5.1.0
 
 ### Minor Changes

package/README.md

@@ -18,7 +18,9 @@
 <br clear="left"/>
 
 `process.env` always hands you a `string | undefined`. envapt returns the type you asked for, with a
-fallback that removes `undefined` from the return type.
+fallback that removes `undefined` from the return type. On Node, Bun, and Deno it reads `process.env`
+and your `.env` files; on Cloudflare Workers and in the browser you bind the source with
+`Envapter.useSource(...)`.
 
 ```ts
 import { Envapter } from 'envapt';
@@ -35,9 +37,12 @@ const port = Envapter.getNumber('PORT', 3000); // number, not string | undefined
   your own function or a Standard Schema validator (zod, valibot, arktype).
 - **Zero runtime dependencies.** envapt ships its own `.env` parser, so nothing is added to your
   dependency tree.
-- **Runs on Node, Bun, and Deno.** Node `>=20`, Bun `>=1.3`, Deno `>=2.5`; ESM and CJS.
-- **`.env` loading built in.** A per-environment file cascade, `${VAR}` templates, and strict /
-  required checks.
+- **Runs on Node, Bun, Deno, Cloudflare Workers, and the browser.** Node `>=20`, Bun `>=1.3`, Deno
+  `>=2.5` (ESM and CJS); the Workers and browser builds resolve through the package `exports`
+  conditions.
+- **`.env` loading on Node, Bun, and Deno.** A per-environment file cascade, `${VAR}` templates, and
+  strict / required checks. Off Node there is no filesystem, so you bind a source with
+  `Envapter.useSource(...)` and read with the same typed API.
 
 ## Install
 
@@ -56,7 +61,8 @@ Both share the same parsing, converters, and cache.
 
 ### Functional
 
-Read a value from any call site, in JavaScript or TypeScript. No build step.
+Read a value from any call site, in JavaScript or TypeScript. No build step. On Node the source is
+bound for you; on Workers and in the browser, call `Envapter.useSource(...)` first.
 
 ```ts
 import { Envapter, Converters } from 'envapt';
@@ -65,6 +71,18 @@ const port = Envapter.getNumber('PORT', 3000);
 const origins = Envapter.getUsing('ALLOWED_ORIGINS', Converters.array(), []);
 ```
 
+On Cloudflare Workers, `env` is importable at module scope, so bind it once in a config module; in the
+browser, seed a `ManualEnvSource` from the object your bundler injects.
+
+```ts
+import { env } from 'cloudflare:workers';
+import { Envapter, WorkerEnvSource } from 'envapt';
+
+Envapter.useSource(new WorkerEnvSource(env));
+
+export const apiToken = Envapter.get('API_TOKEN');
+```
+
 ### Decorator
 
 Bind a value to a class field. TypeScript, with `experimentalDecorators` in your `tsconfig.json`.

package/dist/browser/Debug.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Debug.d.mts","names":[],"sources":["../../src/Debug.ts"],"mappings":";;AAWA;;;;AAAsB;;;KAAV,UAAA"}

package/dist/browser/Debug.mjs

@@ -0,0 +1,2 @@
+import{EnvaptError as e}from"./Error.mjs";import{readRuntimeEnv as t,writeRuntimeLine as n}from"./runtime.mjs";const r=new Set([`silent`,`warn`,`verbose`]);let i=`silent`,a=!1;function o(e){return e!==void 0&&r.has(e)}function s(){if(!a){let e=t().ENVAPT_DEBUG;i=o(e)?e:`silent`,a=!0}return i}function c(t){if(!o(t))throw new e(302,`Invalid debug level "${String(t)}". Expected 'silent' | 'warn' | 'verbose'.`);i=t,a=!0}function l(){return s()}function u(e){let t=s();(t===`warn`||t===`verbose`)&&n(`[envapt] ${e}`)}function d(e){s()===`verbose`&&n(`[envapt] ${e}`)}export{d as debugVerbose,u as debugWarn,l as getDebugLevel,c as setDebugLevel};
+//# sourceMappingURL=Debug.mjs.map

package/dist/browser/Debug.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Debug.mjs","names":[],"sources":["../../src/Debug.ts"],"sourcesContent":["import { EnvaptError, EnvaptErrorCodes } from './Error';\nimport { readRuntimeEnv, writeRuntimeLine } from './runtime';\n\n/**\n * Debug log levels for {@link Envapter.debug}. `silent` (default) emits nothing.\n * `warn` covers signals that might indicate misconfiguration: failed file reads,\n * unresolved templates (when not strict), fallback values used in place of missing\n * env. `verbose` adds every loaded file, per-file key count, per-key load lines, and\n * effective-paths / cache-rebuild notices.\n * @public\n */\nexport type DebugLevel = 'silent' | 'warn' | 'verbose';\n\nconst VALID_LEVELS: ReadonlySet<string> = new Set<DebugLevel>(['silent', 'warn', 'verbose']);\n\nlet currentLevel: DebugLevel = 'silent';\nlet initialized = false;\n\nfunction isDebugLevel(value: string | undefined): value is DebugLevel {\n    return value !== undefined && VALID_LEVELS.has(value);\n}\n\n// Reads `ENVAPT_DEBUG` lazily on first access. Setter wins after that.\nfunction resolveLevel(): DebugLevel {\n    if (!initialized) {\n        const fromEnv = readRuntimeEnv().ENVAPT_DEBUG;\n        currentLevel = isDebugLevel(fromEnv) ? fromEnv : 'silent';\n        initialized = true;\n    }\n    return currentLevel;\n}\n\n/** @internal */\nexport function setDebugLevel(level: DebugLevel): void {\n    if (!isDebugLevel(level)) {\n        throw new EnvaptError(\n            EnvaptErrorCodes.InvalidUserDefinedConfig,\n            `Invalid debug level \"${String(level)}\". Expected 'silent' | 'warn' | 'verbose'.`\n        );\n    }\n    currentLevel = level;\n    initialized = true;\n}\n\n/** @internal */\nexport function getDebugLevel(): DebugLevel {\n    return resolveLevel();\n}\n\n/** @internal */\nexport function resetDebugForTesting(): void {\n    currentLevel = 'silent';\n    initialized = false;\n}\n\n/** @internal */\nexport function debugWarn(message: string): void {\n    const level = resolveLevel();\n    if (level === 'warn' || level === 'verbose') {\n        writeRuntimeLine(`[envapt] ${message}`);\n    }\n}\n\n/** @internal */\nexport function debugVerbose(message: string): void {\n    if (resolveLevel() === 'verbose') {\n        writeRuntimeLine(`[envapt] ${message}`);\n    }\n}\n"],"mappings":"+GAaA,MAAM,EAAoC,IAAI,IAAgB,CAAC,SAAU,OAAQ,SAAS,CAAC,EAE3F,IAAI,EAA2B,SAC3B,EAAc,GAElB,SAAS,EAAa,EAAgD,CAClE,OAAO,IAAU,IAAA,IAAa,EAAa,IAAI,CAAK,CACxD,CAGA,SAAS,GAA2B,CAChC,GAAI,CAAC,EAAa,CACd,IAAM,EAAU,EAAe,EAAE,aACjC,EAAe,EAAa,CAAO,EAAI,EAAU,SACjD,EAAc,EAClB,CACA,OAAO,CACX,CAGA,SAAgB,EAAc,EAAyB,CACnD,GAAI,CAAC,EAAa,CAAK,EACnB,MAAM,IAAI,EAAA,IAEN,wBAAwB,OAAO,CAAK,EAAE,2CAC1C,EAEJ,EAAe,EACf,EAAc,EAClB,CAGA,SAAgB,GAA4B,CACxC,OAAO,EAAa,CACxB,CASA,SAAgB,EAAU,EAAuB,CAC7C,IAAM,EAAQ,EAAa,GACvB,IAAU,QAAU,IAAU,YAC9B,EAAiB,YAAY,GAAS,CAE9C,CAGA,SAAgB,EAAa,EAAuB,CAC5C,EAAa,IAAM,WACnB,EAAiB,YAAY,GAAS,CAE9C"}

package/dist/{Dotenv.d.mts → browser/Dotenv.d.mts}

@@ -8,7 +8,7 @@
  */
 interface EnvFileOptions {
   /** Encoding for reading .env files. Defaults to 'utf8'. */
-  encoding?: BufferEncoding;
+  encoding?: string;
   /** When true, later files override earlier ones (and existing processEnv values). Default false (first-wins). */
   override?: boolean;
 }

package/dist/browser/Dotenv.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Dotenv.d.mts","names":[],"sources":["../../src/Dotenv.ts"],"mappings":";;AASA;;;;AAIY;;UAJK,cAAA;;EAEb,QAAA;;EAEA,QAAQ;AAAA"}

package/dist/browser/Dotenv.mjs

@@ -0,0 +1,3 @@
+import{debugVerbose as e,debugWarn as t}from"./Debug.mjs";const n=/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/u;function r(e){let t=new Map,n=e.split(/\r?\n/u);for(let e=0;e<n.length;e++){let r=i(n,e);e=r.endLine,r.entry&&t.set(r.entry.key,r.entry.value)}return t}function i(e,t){let r=e[t]??``,i=r.trim();if(i===``||i.startsWith(`#`))return{entry:void 0,endLine:t};let s=r.match(n);if(!s)return{entry:void 0,endLine:t};let c=s[1],l=(s[2]??``).replace(/^\s+/u,``),u=l[0];if(u===`"`||u===`'`||u==="`"){let n=a(l,e,t,u);return{entry:{key:c,value:n.value},endLine:n.endLine}}return{entry:{key:c,value:o(l)},endLine:t}}function a(e,t,n,r){let i=e,a=n,o=c(i,r);for(;o<0&&a<t.length-1;)a++,i+=`\n${t[a]??``}`,o=c(i,r);let s=o>0?i.slice(1,o):i.slice(1);return{value:r===`"`?l(s):s,endLine:a}}function o(e){let t=s(e);return(t===-1?e:e.slice(0,t)).trimEnd()}function s(e){for(let t=0;t<e.length;t++)if(e[t]===`#`&&(t===0||/\s/u.test(e[t-1])))return t;return-1}function c(e,t){for(let n=e.length-1;n>0;n--)if(e[n]===t){if(t===`"`){let t=0,r=n-1;for(;r>=0&&e[r]===`\\`;)t++,r--;if(t%2==1)continue}return n}return-1}function l(e){let t=``;for(let n=0;n<e.length;n++){let r=e[n];if(r!==`\\`||n===e.length-1){t+=r;continue}let i=e[n+1];switch(n++,i){case`n`:t+=`
+`;break;case`r`:t+=`\r`;break;case`t`:t+=`	`;break;case`\\`:t+=`\\`;break;case`"`:t+=`"`;break;default:t+=`\\${i??``}`}}return t}function u(n){let i=Array.isArray(n.path)?n.path:[n.path],a=n.encoding??`utf8`,o=n.override??!1,s=new Set;for(let c of i){let i=n.readFile(c,a);if(i===void 0){t(`could not read ${c}`);continue}let l=r(i);e(`loaded ${c}: ${l.size} ${l.size===1?`key`:`keys`}`);for(let[t,r]of l)(!Object.prototype.hasOwnProperty.call(n.processEnv,t)||o)&&(n.processEnv[t]=r,s.add(t),e(`${c} -> ${t}`))}return s}export{u as loadDotenv};
+//# sourceMappingURL=Dotenv.mjs.map

package/dist/browser/Dotenv.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Dotenv.mjs","names":[],"sources":["../../src/Dotenv.ts"],"sourcesContent":["import { debugVerbose, debugWarn } from './Debug';\n\n/**\n * Public options for the internal `.env` loader. Mirrors the subset of dotenv's\n * `config()` options that envapt actually supports (no DOTENV_KEY, no quiet).\n * For debug output, use `Envapter.debug` (or the `ENVAPT_DEBUG` env var).\n *\n * @public\n */\nexport interface EnvFileOptions {\n    /** Encoding for reading .env files. Defaults to 'utf8'. */\n    encoding?: string;\n    /** When true, later files override earlier ones (and existing processEnv values). Default false (first-wins). */\n    override?: boolean;\n}\n\n/**\n * Internal call signature used by `EnvapterBase`. The `path` and `processEnv`\n * fields are managed by envapt and never user-supplied.\n * @internal\n */\nexport interface LoadDotenvInput extends EnvFileOptions {\n    path: string | string[];\n    processEnv: Record<string, string>;\n    // Injected so the loader stays free of `node:fs`. Returns `undefined` when the file is absent.\n    readFile(path: string, encoding: string): string | undefined;\n}\n\n// Matches: optional `export`, KEY name, optional whitespace, `=`, optional whitespace, value tail.\n// Multi-line quoted values are handled by re-buffering subsequent lines below.\n// Bounded by anchors with linear-time quantifiers; no catastrophic backtracking risk -- justified\n// eslint-disable-next-line security/detect-unsafe-regex\nconst KEY_LINE_RE = /^\\s*(?:export\\s+)?([A-Za-z_][A-Za-z0-9_]*)\\s*=(.*)$/u;\n\n/**\n * Parse a `.env` text blob into a `Map<string, string>`.\n *\n * Supported syntax:\n * - `KEY=value` and `export KEY=value`\n * - blank lines and full-line `# comments`\n * - single-quoted `'literal'` values (no escape interpretation)\n * - double-quoted `\"value\"` values (interprets `\\n`, `\\r`, `\\t`, `\\\\`, `\\\"`)\n * - backtick-quoted values (literal, like single quotes)\n * - quoted values may span multiple lines\n * - inline `# comment` after an unquoted value (requires whitespace before `#`)\n * - empty values resolve to `\"\"`\n *\n * Mirrors dotenv's quirk where unescaped inner quotes inside a quoted value\n * are tolerated by greedy-matching to the rightmost matching quote on the\n * (possibly multi-line) value buffer. This is what lets a value like\n * `JSON=\"{\"name\":\"x\"}\"` round-trip without escaping.\n *\n * Does NOT perform `${VAR}` expansion — envapt's `Parser` handles that downstream.\n * @internal\n */\nexport function parseDotenv(src: string): Map<string, string> {\n    const out = new Map<string, string>();\n    const lines = src.split(/\\r?\\n/u);\n\n    for (let i = 0; i < lines.length; i++) {\n        const consumed = parseEntry(lines, i);\n        i = consumed.endLine;\n        if (consumed.entry) out.set(consumed.entry.key, consumed.entry.value);\n    }\n\n    return out;\n}\n\ninterface ParsedEntry {\n    key: string;\n    value: string;\n}\n\nfunction parseEntry(lines: string[], start: number): { entry: ParsedEntry | undefined; endLine: number } {\n    /* v8 ignore next -- @preserve caller bounds-checks start so this never falls back */\n    const line = lines[start] ?? '';\n    const trimmedLine = line.trim();\n    if (trimmedLine === '' || trimmedLine.startsWith('#')) return { entry: undefined, endLine: start };\n\n    const match = line.match(KEY_LINE_RE);\n    if (!match) return { entry: undefined, endLine: start };\n\n    const key = match[1] as string;\n    // Drop only leading whitespace before the value; trailing whitespace and inline comments\n    // are dealt with below depending on whether the value is quoted.\n    /* v8 ignore next -- @preserve regex group 2 always matches via `(.*)`, fallback is defensive */\n    const rest = (match[2] ?? '').replace(/^\\s+/u, '');\n    const firstChar = rest[0];\n\n    if (firstChar === '\"' || firstChar === \"'\" || firstChar === '`') {\n        const consumed = consumeQuotedValue(rest, lines, start, firstChar);\n        return { entry: { key, value: consumed.value }, endLine: consumed.endLine };\n    }\n\n    return { entry: { key, value: stripInlineComment(rest) }, endLine: start };\n}\n\nfunction consumeQuotedValue(\n    firstLineRest: string,\n    lines: string[],\n    startLine: number,\n    quote: string\n): { value: string; endLine: number } {\n    let buffer = firstLineRest;\n    let cursor = startLine;\n    let closeIdx = findLastUnescapedQuote(buffer, quote);\n\n    while (closeIdx < 0 && cursor < lines.length - 1) {\n        cursor++;\n        /* v8 ignore next -- @preserve cursor is bounded by the while condition above */\n        buffer += `\\n${lines[cursor] ?? ''}`;\n        closeIdx = findLastUnescapedQuote(buffer, quote);\n    }\n\n    const inner = closeIdx > 0 ? buffer.slice(1, closeIdx) : buffer.slice(1);\n    return { value: quote === '\"' ? unescapeDouble(inner) : inner, endLine: cursor };\n}\n\nfunction stripInlineComment(value: string): string {\n    const hashIdx = findInlineCommentStart(value);\n    const stripped = hashIdx === -1 ? value : value.slice(0, hashIdx);\n    return stripped.trimEnd();\n}\n\nfunction findInlineCommentStart(value: string): number {\n    for (let i = 0; i < value.length; i++) {\n        if (value[i] === '#' && (i === 0 || /\\s/u.test(value[i - 1] as string))) return i;\n    }\n    return -1;\n}\n\n/**\n * Find the rightmost matching closing quote in `buffer` (skipping index 0 which is the\n * opening quote). For `\"`, a quote preceded by an odd number of backslashes is escaped\n * and ignored. Single and backtick quotes do not unescape.\n */\nfunction findLastUnescapedQuote(buffer: string, quote: string): number {\n    for (let i = buffer.length - 1; i > 0; i--) {\n        if (buffer[i] !== quote) continue;\n        if (quote === '\"') {\n            let backslashes = 0;\n            let k = i - 1;\n            while (k >= 0 && buffer[k] === '\\\\') {\n                backslashes++;\n                k--;\n            }\n            if (backslashes % 2 === 1) continue; // escaped\n        }\n        return i;\n    }\n    return -1;\n}\n\nfunction unescapeDouble(raw: string): string {\n    let out = '';\n    for (let i = 0; i < raw.length; i++) {\n        const ch = raw[i];\n        if (ch !== '\\\\' || i === raw.length - 1) {\n            out += ch;\n            continue;\n        }\n        const next = raw[i + 1];\n        i++;\n        switch (next) {\n            case 'n':\n                out += '\\n';\n                break;\n            case 'r':\n                out += '\\r';\n                break;\n            case 't':\n                out += '\\t';\n                break;\n            case '\\\\':\n                out += '\\\\';\n                break;\n            case '\"':\n                out += '\"';\n                break;\n            default:\n                /* v8 ignore next -- @preserve `next` is always defined when this branch is reached (guarded above) */\n                out += `\\\\${next ?? ''}`;\n        }\n    }\n    return out;\n}\n\n/**\n * Load one or more `.env` files into a target `processEnv` map. Mirrors the\n * subset of dotenv's `config()` semantics that envapt depends on: first-wins\n * across multiple paths by default, optional `override: true`, optional\n * non-UTF8 encoding, missing files are skipped silently.\n *\n * Returns the set of keys actually written into `input.processEnv`. Skipped\n * collisions (under default `override: false`) are NOT included.\n * @internal\n */\nexport function loadDotenv(input: LoadDotenvInput): Set<string> {\n    const paths = Array.isArray(input.path) ? input.path : [input.path];\n    const encoding = input.encoding ?? 'utf8';\n    const override = input.override ?? false;\n    const written = new Set<string>();\n\n    for (const filePath of paths) {\n        const src = input.readFile(filePath, encoding);\n        if (src === undefined) {\n            debugWarn(`could not read ${filePath}`);\n            continue;\n        }\n\n        const parsed = parseDotenv(src);\n        debugVerbose(`loaded ${filePath}: ${parsed.size} ${parsed.size === 1 ? 'key' : 'keys'}`);\n        for (const [key, value] of parsed) {\n            const exists = Object.prototype.hasOwnProperty.call(input.processEnv, key);\n            if (!exists || override) {\n                input.processEnv[key] = value;\n                written.add(key);\n                debugVerbose(`${filePath} -> ${key}`);\n            }\n        }\n    }\n\n    return written;\n}\n"],"mappings":"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"}

package/dist/browser/Envapter.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Envapter.d.mts","names":[],"sources":["../../src/Envapter.ts"],"mappings":";;;;;;AA4BA;;;;;;;;;;;;;;;;;;;;;cAAa,QAAA,SAAiB,eAAA;EA4EX;AAAA;;;;;;;;;;;;;;EAAA,OA5DR,OAAA,CAAQ,OAAA,EAAS,oBAAA,KAAyB,IAAA;;;;EAmBjD,OAAA,CAAQ,OAAA,EAAS,oBAAA,KAAyB,IAAA;;;;;;;;;;;;;SAgBnC,OAAA,CAAA,GAAW,IAAA;EAAA,eAcH,kBAAA;;;;EAWf,OAAA,CAAA,GAAW,IAAA;AAAA"}

package/dist/browser/Envapter.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Envapter.mjs","names":[],"sources":["../../src/Envapter.ts"],"sourcesContent":["import { AdvancedMethods } from './core';\nimport { EnvaptError, EnvaptErrorCodes } from './Error';\n\nexport { EnvaptCache, Environment } from './core';\n\n/**\n * Main configuration class for environment variable management.\n *\n * Provides both static and instance methods for retrieving typed environment variables\n * with support for template resolution, multiple .env files, and environment detection.\n *\n * Extend your own classes from this to define properties with \\@Envapt decorators and get access to environment-variable methods.\n *\n * @example\n * ```ts\n * // Static usage\n * const port = Envapter.getNumber('PORT', 3000);\n * const url = Envapter.get('API_URL', 'http://localhost');\n * const replica = Envapter.get(['READONLY_URL', 'DATABASE_URL'], 'sqlite://memory');\n *\n * // Instance usage\n * const env = new Envapter();\n * const dbUrl = env.get('DATABASE_URL', 'sqlite://memory');\n * const primaryHost = env.get(['PRIMARY_HOST', 'SECONDARY_HOST']);\n * ```\n *\n * @public\n */\nexport class Envapter extends AdvancedMethods {\n    /**\n     * Tagged template literal for resolving environment variables in template strings.\n     *\n     * @example\n     * ```ts\n     * // Given API_HOST=api.example.com and API_PORT=8080 in environment\n     * const endpoint = Envapter.resolve`Connecting to ${'API_HOST'}:${'API_PORT'}`;\n     * // Returns: \"Connecting to api.example.com:8080\"\n     *\n     * // Works with template variables in .env too:\n     * // API_URL=https://${API_HOST}:${API_PORT}\n     * const message = Envapter.resolve`Service endpoint: ${'API_URL'}`;\n     * // Returns: \"Service endpoint: https://api.example.com:8080\"\n     * ```\n     */\n    static resolve(strings: TemplateStringsArray, ...keys: string[]): string {\n        const strict = Envapter.strict;\n        return strings.reduce((result, string, i) => {\n            const envKey = keys[i];\n            if (!envKey) return result + string;\n            const raw = super.get(envKey, '');\n            if (strict && raw.trim() === '') {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.MissingEnvValue,\n                    `Cannot resolve template variable \"\\${${envKey}}\": value is missing or empty.`\n                );\n            }\n            return result + string + raw;\n        }, '');\n    }\n\n    /**\n     * @see {@link Envapter.resolve}\n     */\n    resolve(strings: TemplateStringsArray, ...keys: string[]): string {\n        return Envapter.resolve(strings, ...keys);\n    }\n\n    /**\n     * Assert that one or more environment variables are present and non-empty (post-trim,\n     * after template resolution). Throws `MissingEnvValue` listing every missing key.\n     *\n     * For typed fail-fast in functional code, use `Envapter.getUsing(key, { converter, required: true })`.\n     *\n     * @example\n     * ```ts\n     * Envapter.require('DATABASE_URL');\n     * Envapter.require('DATABASE_URL', 'API_KEY', 'SENTRY_DSN');\n     * ```\n     */\n    static require(...keys: [string, ...string[]]): void {\n        const missing: string[] = [];\n        for (const k of keys) {\n            if (Envapter.resolveAndValidate(k) === undefined) missing.push(k);\n        }\n\n        if (missing.length > 0) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.MissingEnvValue,\n                `Missing required environment variables: ${missing.join(', ')}.`\n            );\n        }\n    }\n\n    private static resolveAndValidate(key: string): string | undefined {\n        const { value } = this.resolveKeyInput(key);\n        if (value === undefined) return undefined;\n        const resolved = this.templateResolver.resolveTemplate(key, value);\n        if (resolved.trim() === '') return undefined;\n        return resolved;\n    }\n\n    /**\n     * @see {@link Envapter.require}\n     */\n    require(...keys: [string, ...string[]]): void {\n        Envapter.require(...keys);\n    }\n}\n"],"mappings":"6KA4BA,IAAa,EAAb,MAAa,UAAiB,CAAgB,CAgB1C,OAAO,QAAQ,EAA+B,GAAG,EAAwB,CACrE,IAAM,EAAS,EAAS,OACxB,OAAO,EAAQ,QAAQ,EAAQ,EAAQ,IAAM,CACzC,IAAM,EAAS,EAAK,GACpB,GAAI,CAAC,EAAQ,OAAO,EAAS,EAC7B,IAAM,EAAM,MAAM,IAAI,EAAQ,EAAE,EAChC,GAAI,GAAU,EAAI,KAAK,IAAM,GACzB,MAAM,IAAI,EAAA,IAEN,wCAAwC,EAAO,+BACnD,EAEJ,OAAO,EAAS,EAAS,CAC7B,EAAG,EAAE,CACT,CAKA,QAAQ,EAA+B,GAAG,EAAwB,CAC9D,OAAO,EAAS,QAAQ,EAAS,GAAG,CAAI,CAC5C,CAcA,OAAO,QAAQ,GAAG,EAAmC,CACjD,IAAM,EAAoB,CAAC,EAC3B,IAAK,IAAM,KAAK,EACR,EAAS,mBAAmB,CAAC,IAAM,IAAA,IAAW,EAAQ,KAAK,CAAC,EAGpE,GAAI,EAAQ,OAAS,EACjB,MAAM,IAAI,EAAA,IAEN,2CAA2C,EAAQ,KAAK,IAAI,EAAE,EAClE,CAER,CAEA,OAAe,mBAAmB,EAAiC,CAC/D,GAAM,CAAE,SAAU,KAAK,gBAAgB,CAAG,EAC1C,GAAI,IAAU,IAAA,GAAW,OACzB,IAAM,EAAW,KAAK,iBAAiB,gBAAgB,EAAK,CAAK,EAC7D,KAAS,KAAK,IAAM,GACxB,OAAO,CACX,CAKA,QAAQ,GAAG,EAAmC,CAC1C,EAAS,QAAQ,GAAG,CAAI,CAC5B,CACJ"}

package/dist/{Error.d.mts → browser/Error.d.mts}

@@ -10,7 +10,7 @@ declare enum EnvaptErrorCodes {
   ArrayFallbackElementTypeMismatch = 103,
   /** Thrown when fallback type doesn't match the specified converter */
   FallbackConverterTypeMismatch = 104,
-  /** Thrown when a time-string fallback is malformed (does not match the required `<integer><unit>` format) */
+  /** Thrown when a time-string fallback is malformed (does not match the required `<number><unit>` format) */
   MalformedTimeFallback = 105,
   /** Thrown when invalid array converter configuration is provided */
   InvalidArrayConverterType = 201,
@@ -39,7 +39,11 @@ declare enum EnvaptErrorCodes {
   /** Thrown when no valid environment key is provided */
   InvalidKeyInput = 304,
   /** Thrown when a required environment value is missing or empty (post-trim) */
-  MissingEnvValue = 305
+  MissingEnvValue = 305,
+  /** Thrown when a file-based API (envPaths, baseDir, configureProfiles) is used on a source without filesystem support */
+  FileApiUnsupported = 306,
+  /** Thrown when an environment value is read before a source is bound via Envapter.useSource */
+  NoSourceBound = 307
 }
 interface EnvaptErrorOptions {
   issues?: readonly StandardSchemaV1.Issue[];

package/dist/browser/Error.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Error.d.mts","names":[],"sources":["../../src/Error.ts"],"mappings":";;;aAGY,gBAAA;;EAGR,eAAA;EAHwB;EAKxB,mBAAA;EALwB;EAOxB,gCAAA;EAFA;EAIA,6BAAA;EAAA;EAEA,qBAAA;EAIA;EAAA,yBAAA;EAIA;EAFA,uBAAA;EAMA;EAJA,sBAAA;EAQA;EANA,oBAAA;EAUA;EARA,uBAAA;EAeA;EAbA,4BAAA;EAiBA;EAfA,iBAAA;EAmBA;EAjBA,sBAAA;EAmBa;EAjBb,WAAA;EAoBM;EAfN,gBAAA;;EAEA,wBAAA;EAcA;EAZA,gBAAA;EAYmC;EAVnC,eAAA;EAWK;EATL,eAAA;EAoBS;EAlBT,kBAAA;;EAEA,aAAA;AAAA;AAAA,UAGM,kBAAA;EACN,MAAA,YAAkB,gBAAA,CAAiB,KAAK;EACxC,KAAA;AAAA;;;;;;;;;cAWS,WAAA,SAAoB,KAAA;EAAA,SACb,IAAA,EAAM,gBAAA;EAQc;;;;AAA6C;EAA7C,SAFpB,MAAA,WAAiB,gBAAA,CAAiB,KAAA;cAEtC,IAAA,EAAM,gBAAA,EAAkB,OAAA,UAAiB,OAAA,GAAU,kBAAA;AAAA"}

package/dist/{Error.mjs → browser/Error.mjs}

@@ -1,2 +1,2 @@
-let e=function(e){return e[e.InvalidFallback=101]=`InvalidFallback`,e[e.InvalidFallbackType=102]=`InvalidFallbackType`,e[e.ArrayFallbackElementTypeMismatch=103]=`ArrayFallbackElementTypeMismatch`,e[e.FallbackConverterTypeMismatch=104]=`FallbackConverterTypeMismatch`,e[e.MalformedTimeFallback=105]=`MalformedTimeFallback`,e[e.InvalidArrayConverterType=201]=`InvalidArrayConverterType`,e[e.InvalidBuiltInConverter=202]=`InvalidBuiltInConverter`,e[e.InvalidCustomConverter=203]=`InvalidCustomConverter`,e[e.InvalidConverterType=204]=`InvalidConverterType`,e[e.PrimitiveCoercionFailed=205]=`PrimitiveCoercionFailed`,e[e.ArrayElementConversionFailed=206]=`ArrayElementConversionFailed`,e[e.EmptyArrayElement=207]=`EmptyArrayElement`,e[e.SchemaValidationFailed=208]=`SchemaValidationFailed`,e[e.SchemaThrew=209]=`SchemaThrew`,e[e.MissingDelimiter=301]=`MissingDelimiter`,e[e.InvalidUserDefinedConfig=302]=`InvalidUserDefinedConfig`,e[e.EnvFilesNotFound=303]=`EnvFilesNotFound`,e[e.InvalidKeyInput=304]=`InvalidKeyInput`,e[e.MissingEnvValue=305]=`MissingEnvValue`,e}({});var t=class extends Error{code;issues;constructor(e,t,n){super(t,n?.cause===void 0?void 0:{cause:n.cause}),this.name=`EnvaptError [${e}]`,this.code=e,this.issues=n?.issues}};export{t as EnvaptError,e as EnvaptErrorCodes};
+let e=function(e){return e[e.InvalidFallback=101]=`InvalidFallback`,e[e.InvalidFallbackType=102]=`InvalidFallbackType`,e[e.ArrayFallbackElementTypeMismatch=103]=`ArrayFallbackElementTypeMismatch`,e[e.FallbackConverterTypeMismatch=104]=`FallbackConverterTypeMismatch`,e[e.MalformedTimeFallback=105]=`MalformedTimeFallback`,e[e.InvalidArrayConverterType=201]=`InvalidArrayConverterType`,e[e.InvalidBuiltInConverter=202]=`InvalidBuiltInConverter`,e[e.InvalidCustomConverter=203]=`InvalidCustomConverter`,e[e.InvalidConverterType=204]=`InvalidConverterType`,e[e.PrimitiveCoercionFailed=205]=`PrimitiveCoercionFailed`,e[e.ArrayElementConversionFailed=206]=`ArrayElementConversionFailed`,e[e.EmptyArrayElement=207]=`EmptyArrayElement`,e[e.SchemaValidationFailed=208]=`SchemaValidationFailed`,e[e.SchemaThrew=209]=`SchemaThrew`,e[e.MissingDelimiter=301]=`MissingDelimiter`,e[e.InvalidUserDefinedConfig=302]=`InvalidUserDefinedConfig`,e[e.EnvFilesNotFound=303]=`EnvFilesNotFound`,e[e.InvalidKeyInput=304]=`InvalidKeyInput`,e[e.MissingEnvValue=305]=`MissingEnvValue`,e[e.FileApiUnsupported=306]=`FileApiUnsupported`,e[e.NoSourceBound=307]=`NoSourceBound`,e}({});var t=class extends Error{code;issues;constructor(e,t,n){super(t,n?.cause===void 0?void 0:{cause:n.cause}),this.name=`EnvaptError [${e}]`,this.code=e,this.issues=n?.issues}};export{t as EnvaptError,e as EnvaptErrorCodes};
 //# sourceMappingURL=Error.mjs.map

package/dist/browser/Error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Error.mjs","names":[],"sources":["../../src/Error.ts"],"sourcesContent":["/* eslint-disable no-magic-numbers */\nimport type { StandardSchemaV1 } from './StandardSchema';\n\nexport enum EnvaptErrorCodes {\n    // Fallback related errors\n    /** Thrown when an invalid fallback value is provided */\n    InvalidFallback = 101,\n    /** Thrown when fallback value type doesn't match expected converter type */\n    InvalidFallbackType = 102,\n    /** Thrown when array fallback contains elements of wrong type */\n    ArrayFallbackElementTypeMismatch = 103,\n    /** Thrown when fallback type doesn't match the specified converter */\n    FallbackConverterTypeMismatch = 104,\n    /** Thrown when a time-string fallback is malformed (does not match the required `<number><unit>` format) */\n    MalformedTimeFallback = 105,\n\n    // Converter related errors\n    /** Thrown when invalid array converter configuration is provided */\n    InvalidArrayConverterType = 201,\n    /** Thrown when an invalid built-in converter is specified */\n    InvalidBuiltInConverter = 202,\n    /** Thrown when a custom converter is not a function */\n    InvalidCustomConverter = 203,\n    /** Thrown when converter type is not recognized */\n    InvalidConverterType = 204,\n    /** Thrown when primitive type coercion on fallback value fails */\n    PrimitiveCoercionFailed = 205,\n    /** Thrown when an array element fails to convert to the configured element type */\n    ArrayElementConversionFailed = 206,\n    /** Thrown under strict mode when an array element is empty or whitespace only */\n    EmptyArrayElement = 207,\n    /** Thrown when a Standard Schema returns issues for a non-empty env value */\n    SchemaValidationFailed = 208,\n    /** Thrown when a Standard Schema's `validate` itself throws (e.g. a refinement that crashes) */\n    SchemaThrew = 209,\n\n    // Other errors\n    /** Thrown when delimiter is missing in array converter configuration */\n    // This doesn't happen because 203 is thrown when object without delimiter is passed\n    MissingDelimiter = 301,\n    /** Thrown when invalid user-defined configuration is provided */\n    InvalidUserDefinedConfig = 302,\n    /** Thrown when specified environment files don't exist */\n    EnvFilesNotFound = 303,\n    /** Thrown when no valid environment key is provided */\n    InvalidKeyInput = 304,\n    /** Thrown when a required environment value is missing or empty (post-trim) */\n    MissingEnvValue = 305,\n    /** Thrown when a file-based API (envPaths, baseDir, configureProfiles) is used on a source without filesystem support */\n    FileApiUnsupported = 306,\n    /** Thrown when an environment value is read before a source is bound via Envapter.useSource */\n    NoSourceBound = 307\n}\n\ninterface EnvaptErrorOptions {\n    issues?: readonly StandardSchemaV1.Issue[];\n    cause?: unknown;\n}\n\n/**\n * Custom error for better DX and debugging when using Envapt.\n *\n * @example\n * ```ts\n * throw new EnvaptError(EnvaptErrorCodes.InvalidFallback, \"Invalid fallback value provided for environment variable.\");\n * ```\n */\nexport class EnvaptError extends Error {\n    public readonly code: EnvaptErrorCodes;\n    /**\n     * Populated only for {@link EnvaptErrorCodes.SchemaValidationFailed} (208). For every other\n     * code this is `undefined`. Lets callers do `if (err.code === 208) err.issues?.forEach(...)`\n     * without a type cast.\n     */\n    public readonly issues: readonly StandardSchemaV1.Issue[] | undefined;\n\n    constructor(code: EnvaptErrorCodes, message: string, options?: EnvaptErrorOptions) {\n        super(message, options?.cause !== undefined ? { cause: options.cause } : undefined);\n        this.name = `EnvaptError [${code}]`;\n        this.code = code;\n        this.issues = options?.issues;\n    }\n}\n"],"mappings":"AAGA,IAAY,EAAL,SAAA,EAAA,OAGH,GAAA,EAAA,gBAAA,KAAA,kBAEA,EAAA,EAAA,oBAAA,KAAA,sBAEA,EAAA,EAAA,iCAAA,KAAA,mCAEA,EAAA,EAAA,8BAAA,KAAA,gCAEA,EAAA,EAAA,sBAAA,KAAA,wBAIA,EAAA,EAAA,0BAAA,KAAA,4BAEA,EAAA,EAAA,wBAAA,KAAA,0BAEA,EAAA,EAAA,uBAAA,KAAA,yBAEA,EAAA,EAAA,qBAAA,KAAA,uBAEA,EAAA,EAAA,wBAAA,KAAA,0BAEA,EAAA,EAAA,6BAAA,KAAA,+BAEA,EAAA,EAAA,kBAAA,KAAA,oBAEA,EAAA,EAAA,uBAAA,KAAA,yBAEA,EAAA,EAAA,YAAA,KAAA,cAKA,EAAA,EAAA,iBAAA,KAAA,mBAEA,EAAA,EAAA,yBAAA,KAAA,2BAEA,EAAA,EAAA,iBAAA,KAAA,mBAEA,EAAA,EAAA,gBAAA,KAAA,kBAEA,EAAA,EAAA,gBAAA,KAAA,kBAEA,EAAA,EAAA,mBAAA,KAAA,qBAEA,EAAA,EAAA,cAAA,KAAA,iBACJ,EAAA,CAAA,CAAA,EAeA,IAAa,EAAb,cAAiC,KAAM,CACnC,KAMA,OAEA,YAAY,EAAwB,EAAiB,EAA8B,CAC/E,MAAM,EAAS,GAAS,QAAU,IAAA,GAAuC,IAAA,GAA3B,CAAE,MAAO,EAAQ,KAAM,CAAa,EAClF,KAAK,KAAO,gBAAgB,EAAK,GACjC,KAAK,KAAO,EACZ,KAAK,OAAS,GAAS,MAC3B,CACJ"}

package/dist/browser/StandardSchema.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StandardSchema.d.mts","names":[],"sources":["../../src/StandardSchema.ts"],"mappings":";;AAWA;;;;;;;;;;UAAiB,gBAAA,2BAA2C,KAAA;EAAA,SAC/C,WAAA,EAAa,gBAAA,CAAiB,KAAA,CAAM,KAAA,EAAO,MAAA;AAAA;AAAA,kBAIvC,gBAAA;EAAA,UACI,KAAA,2BAAgC,KAAA;IAAA,SACpC,OAAA;IAAA,SACA,MAAA;IAAA,SACA,QAAA,GAAW,KAAA,cAAmB,MAAA,CAAO,MAAA,IAAU,OAAA,CAAQ,MAAA,CAAO,MAAA;IAAA,SAC9D,KAAA,GAAQ,KAAA,CAAM,KAAA,EAAO,MAAA;EAAA;EAAA,KAGtB,MAAA,WAAiB,aAAA,CAAc,MAAA,IAAU,aAAA;EAAA,UAEpC,aAAA;IAAA,SACJ,KAAA,EAAO,MAAA;IAAA,SACP,MAAA;EAAA;EAAA,UAGI,aAAA;IAAA,SACJ,MAAA,WAAiB,KAAA;EAAA;EAAA,UAGb,KAAA;IAAA,SACJ,OAAA;IAAA,SACA,IAAA,aAAiB,WAAA,GAAc,WAAA;EAAA;EAAA,UAG3B,WAAA;IAAA,SACJ,GAAA,EAAK,WAAA;EAAA;EAAA,UAGD,KAAA,2BAAgC,KAAA;IAAA,SACpC,KAAA,EAAO,KAAA;IAAA,SACP,MAAA,EAAQ,MAAA;EAAA;EAAA,KAGT,UAAA,gBAA0B,gBAAA,IAAoB,WAAA,CAAY,MAAA;EAAA,KAE1D,WAAA,gBAA2B,gBAAA,IAAoB,WAAA,CAAY,MAAA;AAAA;;;;;;;KAS/D,iBAAA,gBAAiC,gBAAA,IAAoB,gBAAA,CAAiB,WAAA,CAAY,MAAA;;;;;KAMlF,gBAAA,gBAAgC,gBAAA,IAAoB,gBAAA,CAAiB,UAAA,CAAW,MAAA"}

package/dist/browser/TemplateResolver.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TemplateResolver.d.mts","names":[],"sources":["../../src/TemplateResolver.ts"],"mappings":";;;;;AAUA;;;cAAa,gBAAA;EAAA,iBAGoB,UAAA;EAAA,iBAFZ,cAAA;cAEY,UAAA,EAAY,eAAA;EAEzC,eAAA,CAAgB,GAAA,UAAa,KAAA,UAAe,KAAA,GAAO,GAAG;AAAA"}

package/dist/browser/TemplateResolver.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"TemplateResolver.mjs","names":[],"sources":["../../src/TemplateResolver.ts"],"sourcesContent":["import { debugWarn } from './Debug';\nimport { EnvaptError, EnvaptErrorCodes } from './Error';\n\nimport type { EnvapterService } from './types/Env';\n\n/**\n * Resolve `${VAR}` template references in environment values, guarding against circular\n * references and missing variables.\n * @internal\n */\nexport class TemplateResolver {\n    private readonly TEMPLATE_REGEX = /\\${\\w*}/g;\n\n    constructor(private readonly envService: EnvapterService) {}\n\n    resolveTemplate(key: string, value: string, stack: Set<string> = new Set<string>()): string {\n        stack.add(key);\n        const strict = this.envService.isStrict();\n\n        const out = value.replace(this.TEMPLATE_REGEX, (template) => {\n            const variable = template.slice(2, -1);\n\n            if (stack.has(variable)) return template; // cycle, preserve\n\n            const raw = this.envService.getRaw(variable);\n            const isMissing = raw === undefined || raw === '' || (strict && raw.trim() === '');\n            if (isMissing) {\n                if (strict) {\n                    throw new EnvaptError(\n                        EnvaptErrorCodes.MissingEnvValue,\n                        `Cannot resolve template variable \"\\${${variable}}\": value is missing or empty.`\n                    );\n                }\n                debugWarn(`unresolved template \\${${variable}} preserved as literal`);\n                return template; // missing or empty, preserve\n            }\n\n            const resolved = this.resolveTemplate(variable, raw, new Set(stack));\n\n            // If resolution still references the current key, skip replacement (indirect cycle)\n            if (resolved.includes(`\\${${key}}`)) return template;\n\n            // If nothing changed (unresolved placeholders stayed), also preserve original template\n            if (resolved === raw && /\\$\\{[^}]*\\}/.test(resolved)) return template;\n\n            return resolved;\n        });\n\n        stack.delete(key);\n        return out;\n    }\n}\n"],"mappings":"kFAUA,IAAa,EAAb,KAA8B,CAGG,WAF7B,eAAkC,WAElC,YAAY,EAA8C,CAA7B,KAAA,WAAA,CAA8B,CAE3D,gBAAgB,EAAa,EAAe,EAAqB,IAAI,IAAuB,CACxF,EAAM,IAAI,CAAG,EACb,IAAM,EAAS,KAAK,WAAW,SAAS,EAElC,EAAM,EAAM,QAAQ,KAAK,eAAiB,GAAa,CACzD,IAAM,EAAW,EAAS,MAAM,EAAG,EAAE,EAErC,GAAI,EAAM,IAAI,CAAQ,EAAG,OAAO,EAEhC,IAAM,EAAM,KAAK,WAAW,OAAO,CAAQ,EAE3C,GADkB,IAAQ,IAAA,IAAa,IAAQ,IAAO,GAAU,EAAI,KAAK,IAAM,GAChE,CACX,GAAI,EACA,MAAM,IAAI,EAAA,IAEN,wCAAwC,EAAS,+BACrD,EAGJ,OADA,EAAU,0BAA0B,EAAS,uBAAuB,EAC7D,CACX,CAEA,IAAM,EAAW,KAAK,gBAAgB,EAAU,EAAK,IAAI,IAAI,CAAK,CAAC,EAQnE,OALI,EAAS,SAAS,MAAM,EAAI,EAAE,GAG9B,IAAa,GAAO,cAAc,KAAK,CAAQ,EAAU,EAEtD,CACX,CAAC,EAGD,OADA,EAAM,OAAO,CAAG,EACT,CACX,CACJ"}

package/dist/browser/Validators.mjs

@@ -0,0 +1,2 @@
+import{EnvaptError as e}from"./Error.mjs";import{isArrayOf as t}from"./converters/Converters.mjs";import{BuiltInConverterTypeCheckers as n,ListOfBuiltInConverters as r}from"./converters/ListOfBuiltInConverters.mjs";var i=class{static isBuiltInConverter(e){return typeof e==`string`?r.includes(e):!1}static isArrayConverter(e){return t(e)}static isStandardSchema(e){if(typeof e!=`object`||!e||!(`~standard`in e))return!1;let t=e[`~standard`];if(typeof t!=`object`||!t)return!1;let n=t;return n.version===1&&typeof n.validate==`function`}static customConvertor(t){if(typeof t!=`function`)throw new e(203,`Custom converter must be a function, got ${typeof t}.`)}static arrayConverter(n){if(!t(n))throw new e(201,`Expected an ArrayOf<...> token produced by Converters.array(...)`);if(typeof n.delimiter!=`string`||n.delimiter.length===0)throw new e(301,`ArrayOf<...> requires a non-empty string delimiter, got ${typeof n.delimiter}`);let i=n.of;if(!(typeof i==`string`&&r.includes(i))&&typeof i!=`function`)throw new e(201,`ArrayOf<...> element ("of") must be a built-in scalar token or a function, got ${typeof i}`)}static builtInConverter(t){if(typeof t!=`string`)throw new e(204,`Expected string, got ${typeof t}`);if(!r.includes(t))throw new e(202,`"${t}" is not a valid converter type. Valid types are: ${r.join(`,`)}`)}static validateBuiltInConverterFallback(t,r){let i=n[t];if(!i(r))throw new e(104,`Fallback type does not match converter "${t}". Expected ${t} compatible type.`)}static validateArrayFallbackElementTypes(t){if(t.length===0)return;let n=typeof t[0];if(t.some((e,t)=>t===0?!1:typeof e!==n))throw new e(103,`All elements in array fallback must have the same type. Found mixed types.`)}static validateArrayConverterElementTypeMatch(t,r){if(r.length===0||typeof t==`function`)return;let i=t;if(i===`time`){let t=r.every(e=>typeof e==`number`),n=r.every(e=>typeof e==`string`);if(!t&&!n)throw new e(103,`Time array fallback must be all numbers or all time-string entries.`);return}let a=n[i],o=r[0];if(!a(o))throw new e(103,`Array converter type "${i}" does not match fallback element type. Expected ${i} compatible elements.`)}static isPrimitiveConstructor(e){return e===String||e===Number||e===Boolean||e===BigInt||e===Symbol}static coercePrimitiveFallback(e,t){return this.isCorrectPrimitiveType(e,t)?t:this.performPrimitiveCoercion(e,t)}static isCorrectPrimitiveType(e,t){return e===String&&typeof t==`string`||e===Number&&typeof t==`number`||e===Boolean&&typeof t==`boolean`||e===BigInt&&typeof t==`bigint`||e===Symbol&&typeof t==`symbol`}static performPrimitiveCoercion(t,n){try{if(t===String)return String(n);if(t===Number)return Number(n);if(t===Boolean)return!!n;if(t===BigInt)return BigInt(n);if(t===Symbol)return Symbol.for(String(n))}catch(n){throw new e(205,`Failed to coerce fallback value using ${t.name}: ${n.message}`)}throw new e(205,`Unknown primitive converter: ${t.name}`)}static validateSyncProcessEnv(t){if(typeof t!=`boolean`)throw new e(302,`Envapter.syncProcessEnv must be a boolean, got ${typeof t}.`)}static validateEnvFileOptions(t){let n=new Set([`encoding`,`override`]),r=Object.keys(t).filter(e=>!n.has(e));if(r.length>0)throw new e(302,`Invalid envFileOptions: ${r.join(`, `)}. Allowed options: ${Array.from(n).join(`, `)}. For debug output, use Envapter.debug or the ENVAPT_DEBUG env var.`);return!0}static validateEnvFilesExist(t,n){let r=t.filter(e=>!n(e));if(r.length>0)throw new e(303,`Environment file not found at path: ${r.join(`, `)}`)}};export{i as Validator};
+//# sourceMappingURL=Validators.mjs.map

package/dist/browser/Validators.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Validators.mjs","names":[],"sources":["../../src/Validators.ts"],"sourcesContent":["// Import the converter modules directly, not via the `./converters` barrel: that barrel pulls in\n// ValueConverter, which imports this Validator, so a barrel import here would cycle.\nimport { isArrayOf } from './converters/Converters';\nimport { ListOfBuiltInConverters, BuiltInConverterTypeCheckers } from './converters/ListOfBuiltInConverters';\nimport { EnvaptError, EnvaptErrorCodes } from './Error';\n\nimport type { ArrayOf, ConverterToken } from './converters/Converters';\nimport type { EnvFileOptions } from './Dotenv';\nimport type { StandardSchemaV1 } from './StandardSchema';\nimport type { BuiltInConverter, ConverterFunction, EnvaptConverter } from './types';\n\nexport class Validator {\n    /**\n     * Check if a value is a built-in scalar converter token\n     */\n    static isBuiltInConverter<TFallback>(value: EnvaptConverter<TFallback>): value is BuiltInConverter {\n        if (typeof value === 'string') return ListOfBuiltInConverters.includes(value);\n        return false;\n    }\n\n    /**\n     * Check if a value is an `ArrayOf<...>` token produced by {@link Converters.array}.\n     */\n    static isArrayConverter(value: unknown): value is ArrayOf {\n        return isArrayOf(value);\n    }\n\n    // Structural check: `version === 1` + callable `validate` is the minimum dispatchable\n    // shape per the Standard Schema spec.\n    static isStandardSchema(value: unknown): value is StandardSchemaV1 {\n        if (typeof value !== 'object' || value === null) return false;\n        if (!('~standard' in value)) return false;\n        const slot = (value as { '~standard': unknown })['~standard'];\n        if (typeof slot !== 'object' || slot === null) return false;\n        const props = slot as { version?: unknown; validate?: unknown };\n        return props.version === 1 && typeof props.validate === 'function';\n    }\n\n    static customConvertor<TFallback>(\n        converter: EnvaptConverter<TFallback>\n    ): asserts converter is ConverterFunction<TFallback> {\n        if (typeof converter !== 'function') {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidCustomConverter,\n                `Custom converter must be a function, got ${typeof converter}.`\n            );\n        }\n    }\n\n    /**\n     * Runtime validation that the `ArrayOf<...>` configuration is well-formed.\n     */\n    static arrayConverter(value: unknown): asserts value is ArrayOf {\n        if (!isArrayOf(value)) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidArrayConverterType,\n                'Expected an ArrayOf<...> token produced by Converters.array(...)'\n            );\n        }\n\n        if (typeof value.delimiter !== 'string' || value.delimiter.length === 0) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.MissingDelimiter,\n                `ArrayOf<...> requires a non-empty string delimiter, got ${typeof value.delimiter}`\n            );\n        }\n\n        const elementOf = value.of;\n        const isScalar = typeof elementOf === 'string' && ListOfBuiltInConverters.includes(elementOf as ConverterToken);\n        const isCustomFn = typeof elementOf === 'function';\n        if (!isScalar && !isCustomFn) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidArrayConverterType,\n                `ArrayOf<...> element (\"of\") must be a built-in scalar token or a function, got ${typeof elementOf}`\n            );\n        }\n    }\n\n    /**\n     * Validate that a string is a valid built-in scalar converter token\n     */\n    static builtInConverter(value: unknown): asserts value is BuiltInConverter {\n        if (typeof value !== 'string') {\n            throw new EnvaptError(EnvaptErrorCodes.InvalidConverterType, `Expected string, got ${typeof value}`);\n        }\n\n        if (!ListOfBuiltInConverters.includes(value as ConverterToken)) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidBuiltInConverter,\n                `\"${value}\" is not a valid converter type. Valid types are: ${ListOfBuiltInConverters.join(',')}`\n            );\n        }\n    }\n\n    /**\n     * Validate that fallback type matches the converter's return type for built-in converters\n     */\n    static validateBuiltInConverterFallback(converter: BuiltInConverter, fallback: unknown): void {\n        const typeChecker = BuiltInConverterTypeCheckers[converter];\n        if (!typeChecker(fallback)) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.FallbackConverterTypeMismatch,\n                `Fallback type does not match converter \"${converter}\". Expected ${converter} compatible type.`\n            );\n        }\n    }\n\n    /**\n     * Validate that all elements in an array fallback have consistent types\n     */\n    static validateArrayFallbackElementTypes(fallback: unknown[]): void {\n        if (fallback.length === 0) return;\n\n        const firstElementType = typeof fallback[0];\n        const hasInconsistentTypes = fallback.some((element, index) => {\n            if (index === 0) return false;\n            return typeof element !== firstElementType;\n        });\n\n        if (hasInconsistentTypes) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.ArrayFallbackElementTypeMismatch,\n                `All elements in array fallback must have the same type. Found mixed types.`\n            );\n        }\n    }\n\n    /**\n     * Validate that an `ArrayOf<...>` element converter matches the runtime types of its\n     * fallback elements. For `Converters.Time` arrays the element-time-string format is also\n     * checked here.\n     */\n    static validateArrayConverterElementTypeMatch(elementOf: ArrayOf['of'], fallback: unknown[]): void {\n        if (fallback.length === 0) return;\n\n        if (typeof elementOf === 'function') {\n            // Custom element converters can return anything; we can't statically validate the fallback shape.\n            return;\n        }\n\n        const elementToken = elementOf;\n\n        // Time array fallbacks may be number[] OR string[] (TimeFallback[]).\n        if (elementToken === 'time') {\n            const everyNumber = fallback.every((v) => typeof v === 'number');\n            const everyString = fallback.every((v) => typeof v === 'string');\n            if (!everyNumber && !everyString) {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.ArrayFallbackElementTypeMismatch,\n                    'Time array fallback must be all numbers or all time-string entries.'\n                );\n            }\n            return;\n        }\n\n        const typeChecker = BuiltInConverterTypeCheckers[elementToken];\n        const firstElement = fallback[0];\n        if (!typeChecker(firstElement)) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.ArrayFallbackElementTypeMismatch,\n                `Array converter type \"${elementToken}\" does not match fallback element type. Expected ${elementToken} compatible elements.`\n            );\n        }\n    }\n\n    /**\n     * Check if a value is a primitive constructor\n     */\n    static isPrimitiveConstructor(\n        value: unknown\n    ): value is typeof String | typeof Number | typeof Boolean | typeof BigInt | typeof Symbol {\n        return value === String || value === Number || value === Boolean || value === BigInt || value === Symbol;\n    }\n\n    /**\n     * Safely coerce a fallback value using a primitive constructor\n     */\n    static coercePrimitiveFallback<CoercedType>(\n        converter: typeof String | typeof Number | typeof Boolean | typeof BigInt | typeof Symbol,\n        fallback: unknown\n    ): CoercedType {\n        if (this.isCorrectPrimitiveType(converter, fallback)) return fallback as CoercedType;\n        return this.performPrimitiveCoercion<CoercedType>(converter, fallback);\n    }\n\n    private static isCorrectPrimitiveType(\n        converter: typeof String | typeof Number | typeof Boolean | typeof BigInt | typeof Symbol,\n        fallback: unknown\n    ): boolean {\n        if (converter === String && typeof fallback === 'string') return true;\n        if (converter === Number && typeof fallback === 'number') return true;\n        if (converter === Boolean && typeof fallback === 'boolean') return true;\n        if (converter === BigInt && typeof fallback === 'bigint') return true;\n        if (converter === Symbol && typeof fallback === 'symbol') return true;\n        return false;\n    }\n\n    private static performPrimitiveCoercion<CoercedType>(\n        converter: typeof String | typeof Number | typeof Boolean | typeof BigInt | typeof Symbol,\n        fallback: unknown\n    ): CoercedType {\n        try {\n            if (converter === String) return String(fallback) as CoercedType;\n            if (converter === Number) return Number(fallback) as CoercedType;\n            if (converter === Boolean) return Boolean(fallback) as CoercedType;\n            if (converter === BigInt) return BigInt(fallback as string | number | bigint) as CoercedType;\n            /* v8 ignore next -- @preserve */\n            if (converter === Symbol) return Symbol.for(String(fallback)) as CoercedType;\n        } catch (error) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.PrimitiveCoercionFailed,\n                `Failed to coerce fallback value using ${converter.name}: ${(error as Error).message}`\n            );\n        }\n\n        /* v8 ignore next -- @preserve */\n        throw new EnvaptError(\n            EnvaptErrorCodes.PrimitiveCoercionFailed,\n            `Unknown primitive converter: ${converter.name}`\n        );\n    }\n\n    /**\n     * Reject non-boolean inputs to `Envapter.syncProcessEnv` so a truthy typo\n     * (`'true'`, `1`, etc.) does not silently enable the mirror.\n     */\n    static validateSyncProcessEnv(value: unknown): asserts value is boolean {\n        if (typeof value !== 'boolean') {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidUserDefinedConfig,\n                `Envapter.syncProcessEnv must be a boolean, got ${typeof value}.`\n            );\n        }\n    }\n\n    /**\n     * Make sure the user hasn't provided prohibited options in their dotenv config\n     */\n    static validateEnvFileOptions(config: object): config is EnvFileOptions {\n        const validKeys = new Set(['encoding', 'override']);\n        const invalidKeys = Object.keys(config).filter((key) => !validKeys.has(key));\n\n        if (invalidKeys.length > 0) {\n            throw new EnvaptError(\n                EnvaptErrorCodes.InvalidUserDefinedConfig,\n                `Invalid envFileOptions: ${invalidKeys.join(', ')}. Allowed options: ${Array.from(validKeys).join(', ')}. For debug output, use Envapter.debug or the ENVAPT_DEBUG env var.`\n            );\n        }\n\n        return true;\n    }\n\n    // Existence is probed through the caller-supplied `fileExists` (backed by the bound source) so\n    // this stays free of `node:fs`.\n    static validateEnvFilesExist(paths: string[], fileExists: (path: string) => boolean): void {\n        const missing = paths.filter((p) => !fileExists(p));\n\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"],"mappings":"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"}

package/dist/browser/converters/BuiltInConverters.mjs

@@ -0,0 +1,2 @@
+import{EnvaptError as e}from"../Error.mjs";const t=1e3,n=60*t,r=60*n,i=24*r,a={ms:1,s:t,m:n,h:r,d:i,w:7*i},o=new RegExp(String.raw`^(\d+(?:\.\d+)?)(ms|s|m|h|d|w)?$`,`u`),s=new RegExp(String.raw`^(\d+(?:\.\d+)?)(ms|s|m|h|d|w)$`,`u`);function c(e,t=!1){let n=e.match(t?s:o);if(!n)return;let[,r,i]=n;if(!r)return;let c=Number.parseFloat(r);if(!Number.isNaN(c))return c*a[i??`ms`]}var l=class t{static string(e,t){return String(e)}static number(e,t){let n=Number(e);return Number.isNaN(n)?t:n}static boolean(e,t){let n=e.toLowerCase().trim();return[`1`,`yes`,`true`,`on`].includes(n)?!0:[`0`,`no`,`false`,`off`].includes(n)?!1:t}static bigint(e,t){try{return BigInt(e)}catch{return t}}static symbol(e,t){try{return e?Symbol.for(e):t}catch{return t}}static integer(e,t){let n=Number.parseInt(e,10);return Number.isNaN(n)?t:n}static float(e,t){let n=Number.parseFloat(e);return Number.isNaN(n)?t:n}static json(e,t){try{return JSON.parse(e)}catch{return t}}static url(e,t){try{return new URL(e)}catch{return t}}static regexp(e,t){try{let t=e.match(new RegExp(String.raw`^\/(.+)\/([gimsuvy]*)$`));return t?new RegExp(t[1],t[2]):new RegExp(e)}catch{return t}}static date(e,t){if(new RegExp(String.raw`^\d+$`).test(e)){let n=new Date(parseInt(e,10));return Number.isNaN(n.getTime())?t:n}if(!new RegExp(String.raw`^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$`,`u`).test(e))return t;let n=new Date(e);return Number.isNaN(n.getTime())?t:n}static time(t,n){let r=c(t);if(r!==void 0)return r;if(typeof n==`number`)return n;if(typeof n==`string`){let t=c(n,!0);if(t===void 0)throw new e(105,`Time-string fallback "${n}" is not a valid format. Expected <number><unit> where unit is one of: ms, s, m, h, d, w.`);return t}}static processArrayConverter(n,r,i=!1){if(n.trim()===``)return[];let a=n.split(r.delimiter).map(e=>String(e).trim());if(i){let t=a.findIndex(e=>e===``);if(t!==-1)throw new e(207,`Array element at index ${t} is empty or whitespace only (strict mode).`)}let o=a.filter(Boolean);if(!o.length)return[];let s=r.of;if(typeof s==`function`)return o.map((t,n)=>{let r=s(t);if(r===void 0)throw new e(206,`Custom element converter returned undefined for item "${t}" at index ${n}.`);return r});let c=t.getConverter(s);return o.map((t,n)=>{let r=c(t,void 0);if(r===void 0)throw new e(206,`Element "${t}" at index ${n} could not be converted to ${s}.`);return r})}static getConverter(e){return{string:t.string,number:t.number,boolean:t.boolean,integer:t.integer,bigint:t.bigint,symbol:t.symbol,float:t.float,json:t.json,url:t.url,regexp:t.regexp,date:t.date,time:t.time}[e]}};export{l as BuiltInConverters};
+//# sourceMappingURL=BuiltInConverters.mjs.map

package/dist/browser/converters/BuiltInConverters.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"BuiltInConverters.mjs","names":["converter"],"sources":["../../../src/converters/BuiltInConverters.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/unbound-method */\n\nimport { EnvaptError, EnvaptErrorCodes } from '../Error';\n\nimport type { ArrayOf, CustomElementConverter } from './Converters';\nimport type {\n    BuiltInConverter,\n    BuiltInConverterFunction,\n    JsonValue,\n    MapOfConverterFunctions,\n    TimeFallback,\n    TimeUnit\n} from '../types';\n\nconst MS_PER_SECOND = 1000;\nconst SECONDS_PER_MINUTE = 60;\nconst MINUTES_PER_HOUR = 60;\nconst HOURS_PER_DAY = 24;\nconst DAYS_PER_WEEK = 7;\nconst MS_PER_MINUTE = SECONDS_PER_MINUTE * MS_PER_SECOND;\nconst MS_PER_HOUR = MINUTES_PER_HOUR * MS_PER_MINUTE;\nconst MS_PER_DAY = HOURS_PER_DAY * MS_PER_HOUR;\nconst MS_PER_WEEK = DAYS_PER_WEEK * MS_PER_DAY;\n\nconst TIME_UNIT_MS: Record<TimeUnit, number> = {\n    ms: 1,\n    s: MS_PER_SECOND,\n    m: MS_PER_MINUTE,\n    h: MS_PER_HOUR,\n    d: MS_PER_DAY,\n    w: MS_PER_WEEK\n};\n\nconst TIME_LOOSE_RE = new RegExp(String.raw`^(\\d+(?:\\.\\d+)?)(ms|s|m|h|d|w)?$`, 'u');\nconst TIME_STRICT_RE = new RegExp(String.raw`^(\\d+(?:\\.\\d+)?)(ms|s|m|h|d|w)$`, 'u');\n\n/**\n * Parse a time string (e.g. `\"30s\"`, `\"1.5h\"`) into milliseconds.\n *\n * @param input - The string to parse.\n * @param strict - When `true`, require an explicit unit (used for fallback strings).\n *                 When `false` (default), treat a missing unit as `ms` (used for raw env values). Both allow decimals.\n * @returns The duration in milliseconds, or `undefined` if the input does not match the expected format.\n * @internal\n */\nfunction parseTimeString(input: string, strict = false): number | undefined {\n    const match = input.match(strict ? TIME_STRICT_RE : TIME_LOOSE_RE);\n    if (!match) return undefined;\n\n    const [, numStr, capturedUnit] = match;\n    if (!numStr) return undefined;\n\n    const value = Number.parseFloat(numStr);\n    if (Number.isNaN(value)) return undefined;\n\n    const unit = (capturedUnit ?? 'ms') as TimeUnit;\n    return value * TIME_UNIT_MS[unit];\n}\n\n/**\n * Built-in converter implementations\n * @internal\n */\nexport class BuiltInConverters {\n    static string(raw: string, _fallback?: string): string | undefined {\n        return String(raw);\n    }\n\n    static number(raw: string, fallback?: number): number | undefined {\n        const parsed = Number(raw);\n        return Number.isNaN(parsed) ? fallback : parsed;\n    }\n\n    static boolean(raw: string, fallback?: boolean): boolean | undefined {\n        const lower = raw.toLowerCase().trim();\n\n        const truthyValues = ['1', 'yes', 'true', 'on'];\n        const falsyValues = ['0', 'no', 'false', 'off'];\n\n        if (truthyValues.includes(lower)) return true;\n        if (falsyValues.includes(lower)) return false;\n        return fallback;\n    }\n\n    static bigint(raw: string, fallback?: bigint): bigint | undefined {\n        try {\n            return BigInt(raw);\n        } catch {\n            return fallback;\n        }\n    }\n\n    static symbol(raw: string, fallback?: symbol): symbol | undefined {\n        try {\n            return raw ? Symbol.for(raw) : fallback;\n        } catch {\n            return fallback;\n        }\n    }\n\n    static integer(raw: string, fallback?: number): number | undefined {\n        const parsed = Number.parseInt(raw, 10);\n        return Number.isNaN(parsed) ? fallback : parsed;\n    }\n\n    static float(raw: string, fallback?: number): number | undefined {\n        const parsed = Number.parseFloat(raw);\n        return Number.isNaN(parsed) ? fallback : parsed;\n    }\n\n    static json(raw: string, fallback?: JsonValue): JsonValue | undefined {\n        try {\n            return JSON.parse(raw) as JsonValue;\n        } catch {\n            return fallback;\n        }\n    }\n\n    static url(raw: string, fallback?: URL): URL | undefined {\n        try {\n            return new URL(raw);\n        } catch {\n            return fallback;\n        }\n    }\n\n    static regexp(raw: string, fallback?: RegExp): RegExp | undefined {\n        try {\n            // Handle flags if provided in format: /pattern/flags\n            const match = raw.match(new RegExp(String.raw`^\\/(.+)\\/([gimsuvy]*)$`));\n            if (match) return new RegExp(match[1] as string, match[2]);\n\n            return new RegExp(raw);\n        } catch {\n            return fallback;\n        }\n    }\n\n    static date(raw: string, fallback?: Date): Date | undefined {\n        // Try parsing as timestamp first (if it's all digits)\n        if (new RegExp(String.raw`^\\d+$`).test(raw)) {\n            const timestamp = parseInt(raw, 10);\n            const parsed = new Date(timestamp);\n            return Number.isNaN(parsed.getTime()) ? fallback : parsed;\n        }\n\n        // Only accept ISO 8601 date strings (strict format)\n        const isoRegex = new RegExp(String.raw`^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z$`, 'u');\n        if (!isoRegex.test(raw)) return fallback;\n\n        const parsed = new Date(raw);\n        return Number.isNaN(parsed.getTime()) ? fallback : parsed;\n    }\n\n    static time(raw: string, fallback?: TimeFallback): number | undefined {\n        const parsedRaw = parseTimeString(raw);\n        if (parsedRaw !== undefined) return parsedRaw;\n\n        // Raw didn't parse so apply fallback\n        if (typeof fallback === 'number') return fallback;\n        if (typeof fallback === 'string') {\n            // A string fallback must name a unit; a unitless number is expressed as a number fallback, not a string.\n            const parsedFallback = parseTimeString(fallback, true);\n            if (parsedFallback === undefined) {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.MalformedTimeFallback,\n                    `Time-string fallback \"${fallback}\" is not a valid format. Expected <number><unit> where unit is one of: ms, s, m, h, d, w.`\n                );\n            }\n            return parsedFallback;\n        }\n        return undefined;\n    }\n\n    /**\n     * Process the raw env value for an {@link ArrayOf} configuration.\n     *\n     * Behaviour:\n     * - Splits on `config.delimiter`, trims each item, and filters out empty entries.\n     * - With a scalar element token: runs each item through the matching built-in converter.\n     *   If any element returns `undefined`, throws `ArrayElementConversionFailed` with positional info.\n     * - With a custom function element: runs each item through the function. Propagates user\n     *   exceptions; treats `undefined` returns as conversion failures (same throw as scalar path).\n     * - Returns `[]` when the raw value is empty/whitespace.\n     * - When `strict` is true, throws `EmptyArrayElement` on any empty/whitespace item instead\n     *   of silently filtering it out.\n     */\n    static processArrayConverter(raw: string, config: ArrayOf, strict = false): unknown[] {\n        if (raw.trim() === '') return [];\n\n        const trimmedItems = raw.split(config.delimiter).map((item) => String(item).trim());\n\n        if (strict) {\n            const emptyIdx = trimmedItems.findIndex((item) => item === '');\n            if (emptyIdx !== -1) {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.EmptyArrayElement,\n                    `Array element at index ${emptyIdx} is empty or whitespace only (strict mode).`\n                );\n            }\n        }\n\n        const items = trimmedItems.filter(Boolean);\n\n        if (!items.length) return [];\n\n        const elementOf = config.of;\n\n        if (typeof elementOf === 'function') {\n            return items.map((item, index) => {\n                const converter = elementOf as CustomElementConverter;\n                const result = converter(item);\n                if (result === undefined) {\n                    throw new EnvaptError(\n                        EnvaptErrorCodes.ArrayElementConversionFailed,\n                        `Custom element converter returned undefined for item \"${item}\" at index ${index}.`\n                    );\n                }\n                return result;\n            });\n        }\n\n        const converter = BuiltInConverters.getConverter(elementOf);\n        return items.map((item, index) => {\n            const converted = converter(item, undefined);\n            if (converted === undefined) {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.ArrayElementConversionFailed,\n                    `Element \"${item}\" at index ${index} could not be converted to ${elementOf}.`\n                );\n            }\n            return converted;\n        });\n    }\n\n    /**\n     * Get the converter function for a built-in converter type\n     */\n    static getConverter<TFallback extends BuiltInConverter>(type: TFallback): BuiltInConverterFunction {\n        const converters: MapOfConverterFunctions = {\n            string: BuiltInConverters.string,\n            number: BuiltInConverters.number,\n            boolean: BuiltInConverters.boolean,\n            integer: BuiltInConverters.integer,\n            bigint: BuiltInConverters.bigint,\n            symbol: BuiltInConverters.symbol,\n            float: BuiltInConverters.float,\n            json: BuiltInConverters.json,\n            url: BuiltInConverters.url,\n            regexp: BuiltInConverters.regexp,\n            date: BuiltInConverters.date,\n            time: BuiltInConverters.time\n        } as const;\n\n        return converters[type];\n    }\n}\n"],"mappings":"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"}

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

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

package/dist/browser/converters/Converters.mjs.map

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

package/dist/browser/converters/ListOfBuiltInConverters.mjs.map

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

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

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

package/dist/browser/converters/ValueConverter.mjs

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

package/dist/browser/converters/ValueConverter.mjs.map

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

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

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

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

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

package/dist/{core → browser/core}/EnvapterBase.d.mts

@@ -1,13 +1,10 @@
 import { DebugLevel } from "../Debug.mjs";
 import { EnvFileOptions } from "../Dotenv.mjs";
 import { EnvKeyInput } from "../types/Env.mjs";
+import { EnvSource, FileEnvSource } from "../types/Source.mjs";
 
 //#region src/core/EnvapterBase.d.ts
-/**
- * Base class for environment variable management
- * Handles configuration, caching, and basic environment loading
- * @internal
- */
+/** @internal */
 declare abstract class EnvapterBase {
   protected static _envPaths: string[];
   protected static _envPathsExplicitlySet: boolean;
@@ -16,6 +13,7 @@ declare abstract class EnvapterBase {
   protected static _strict: boolean;
   protected static _syncProcessEnv: boolean;
   protected static _dotenvAddedKeys: Set<string>;
+  protected static _source: EnvSource;
   /**
    * Enable or disable strict mode. Default `false`. Setting refreshes the cache so
    * previously-cached converted values get re-evaluated under the new rule.
@@ -23,9 +21,9 @@ declare abstract class EnvapterBase {
   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]`.
+   * Set the debug log level. Defaults to `silent`. When unset, reads `ENVAPT_DEBUG` from the
+   * bound source on first access; the setter overrides any env-var value. Output goes to stderr
+   * on Node (the console elsewhere), prefixed with `[envapt]`.
    */
   static set debug(level: DebugLevel);
   static get debug(): DebugLevel;
@@ -43,46 +41,11 @@ declare abstract class EnvapterBase {
   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 assertFileApiSupported(api: string, source: EnvSource): asserts source is FileEnvSource;
+  protected static sourceFileExists(path: string): boolean;
   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;
@@ -95,6 +58,13 @@ declare abstract class EnvapterBase {
    * which is what the `envapt/config` side-effect entry does.
    */
   static load(): void;
+  /**
+   * Bind the environment {@link EnvSource}. On Node the entry binds {@link NodeEnvSource} for you
+   * (a `process.env` snapshot plus the `.env` cascade); on the browser or Workers, pass a
+   * `ManualEnvSource` / `WorkerEnvSource` (or any `EnvSource`) before reading. Clears and rebuilds
+   * the cache.
+   */
+  static useSource(source: EnvSource): void;
   /**
    * Read an environment variable as its raw string, skipping parsing and conversion.
    */

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

@@ -0,0 +1 @@
+{"version":3,"file":"EnvapterBase.d.mts","names":[],"sources":["../../../src/core/EnvapterBase.ts"],"mappings":";;;;;;;uBAesB,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;EAAA,iBAGlB,OAAA,EAAS,SAAA;EAyEiE;;;;EAAA,WAnEhF,MAAA,CAAO,KAAA;EAAA,WAOP,MAAA,CAAA;EAgMY;;;;;EAAA,WAvLZ,KAAA,CAAM,KAAA,EAAO,UAAA;EAAA,WAIb,KAAA,CAAA,GAAS,UAAA;EA/BH;;;;;;;;;;;EAAA,WA8CN,cAAA,CAAe,KAAA;EAAA,WAQf,cAAA,CAAA;EAAA,iBAIM,cAAA,CAAe,KAAA;EAAA,iBAQf,kBAAA,CAAmB,SAAA;EAAA,iBAYnB,sBAAA,CAAuB,GAAA,UAAa,MAAA,EAAQ,SAAA,WAAoB,MAAA,IAAU,aAAA;EAAA,iBAW1E,gBAAA,CAAiB,IAAA;EAAA,iBAOjB,YAAA,CAAA;EAAA,iBAOA,kBAAA,CAAA;EAAA,iBAmBA,qBAAA,CAAA;EAAA,iBAKA,eAAA,CAAgB,QAAA,EAAU,WAAA;IAAgB,GAAA;IAAa,KAAA;EAAA;EAAA,qBA0BnD,MAAA,CAAA,GAAU,GAAA;EA3E4D;;;;;EAAA,OAiHpF,IAAA,CAAA;EAhEU;;;;;;EAAA,OA0EV,SAAA,CAAU,MAAA,EAAQ,SAAA;EAVlB;;;EAmBP,MAAA,CAAO,GAAA,EAAK,WAAA;AAAA"}

package/dist/browser/core/EnvapterBase.mjs

@@ -0,0 +1,2 @@
+import{EnvaptError as e}from"../Error.mjs";import{bindRuntimeFromSource as t}from"../runtime.mjs";import{debugVerbose as n,getDebugLevel as r,setDebugLevel as i}from"../Debug.mjs";import{loadDotenv as a}from"../Dotenv.mjs";import{UnboundEnvSource as o}from"../sources/UnboundEnvSource.mjs";import{Validator as s}from"../Validators.mjs";const c=new Map;var l=class l{static _envPaths=[`.env`];static _envPathsExplicitlySet=!1;static _baseDir=void 0;static _userDefinedEnvFileOptions={};static _strict=!1;static _syncProcessEnv=!1;static _dotenvAddedKeys=new Set;static _source=new o;static set strict(e){l._strict=e,this.refreshCache()}static get strict(){return l._strict}static set debug(e){i(e)}static get debug(){return r()}static set syncProcessEnv(e){s.validateSyncProcessEnv(e);let t=l._syncProcessEnv;l._syncProcessEnv=e,!t&&e&&c.size>0&&this.mirrorToProcessEnv()}static get syncProcessEnv(){return l._syncProcessEnv}static treatAsMissing(e){return!!(e===void 0||e===``||l._strict&&e.trim()===``)}static resolveAgainstBase(e){let t=l._baseDir;if(t===void 0)return e;let n=l._source;return n.supportsFiles?n.resolvePath(t,e):e}static assertFileApiSupported(t,n){if(!n.supportsFiles)throw new e(306,`${t} requires a filesystem-backed source; the bound source does not support .env files.`)}static sourceFileExists(e){let t=l._source;return t.supportsFiles?t.readFile(e,`utf8`)!==void 0:!1}static refreshCache(){c.clear(),l._dotenvAddedKeys=new Set,n(`cache cleared, reloading config`),this.config}static mirrorToProcessEnv(){if(l._dotenvAddedKeys.size===0)return;let e=l._source;if(!e.supportsFiles)return;let t={};for(let e of l._dotenvAddedKeys){let r=c.get(e);typeof r==`string`&&(t[e]=r,n(`mirrored ${e} to the ambient environment`))}e.writeVars(t),n(`mirrored ${l._dotenvAddedKeys.size} keys to the ambient environment`)}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(c.size===0){let e=l._source,t={...e.readVars()},r=new Set;if(e.supportsFiles){let i=this.resolveEffectivePaths();n(`effective .env paths: ${i.length===0?`(none)`:i.join(`, `)}`);try{r=a({...this._userDefinedEnvFileOptions,path:i,processEnv:t,readFile:e.readFile.bind(e)})}catch{}}l._dotenvAddedKeys=r;for(let[e,n]of Object.entries(t))c.set(e,n);n(`cache populated: ${c.size} keys total`),l._syncProcessEnv&&this.mirrorToProcessEnv()}return c}static load(){this.config}static useSource(e){l._source=e,t(e),this.refreshCache()}getRaw(e){return l.resolveKeyInput(e).value}};export{c as EnvaptCache,l as EnvapterBase};
+//# sourceMappingURL=EnvapterBase.mjs.map