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

package/dist/portable/sources/merge.mjs

@@ -1,2 +1,2 @@
-import{EnvaptError as e}from"../infra/Error.mjs";function t(...t){if(t.length===0)throw new e(308,`merge requires at least one source.`);let n=t.filter(e=>e.supportsFiles===!0);if(n.length>1)throw new e(308,`merge accepts at most one filesystem-backed source, so the .env cascade and file APIs route to a single member.`);let r=()=>{let e={};for(let n of t)Object.assign(e,n.readVars());return e},i=n[0];return i?{readVars:r,supportsFiles:!0,readFile:(e,t)=>i.readFile(e,t),resolvePath:(e,t)=>i.resolvePath(e,t),normalizeBaseDir:e=>i.normalizeBaseDir(e),writeVars:e=>i.writeVars(e)}:{readVars:r}}export{t as merge};
+import{EnvaptError as e}from"../infra/Error.mjs";import{normalizeSource as t}from"./normalizeSource.mjs";function n(...n){if(n.length===0)throw new e(308,`merge requires at least one source.`);let r=n.map(t),i=r.filter(e=>e.supportsFiles===!0);if(i.length>1)throw new e(308,`merge accepts at most one filesystem-backed source, so the .env cascade and file APIs route to a single member.`);let a=()=>{let e={};for(let t of r)Object.assign(e,t.readVars());return e},o=r.filter(e=>typeof e.readVar==`function`),s=o.length===0?void 0:e=>{for(let t=o.length-1;t>=0;t--){let n=o[t]?.readVar(e);if(n!==void 0)return n}},c=i[0];if(!c){let e={readVars:a};return s&&(e.readVar=s),e}let l={readVars:a,supportsFiles:!0,readFile:(e,t)=>c.readFile(e,t),resolvePath:(e,t)=>c.resolvePath(e,t),normalizeBaseDir:e=>c.normalizeBaseDir(e),writeVars:e=>c.writeVars(e)};return s&&(l.readVar=s),l}export{n as merge};
 //# sourceMappingURL=merge.mjs.map

package/dist/portable/sources/merge.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"merge.mjs","names":[],"sources":["../../../src/sources/merge.ts"],"sourcesContent":["import { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { FileCapableSource, Source } from '../types';\n\n/**\n * Compose several sources into one, read last-wins. A later member's value overrides an earlier\n * member's value for the same key. Bind the result with `Envapter.useSource`. Throws\n * {@link EnvaptErrorCodes.InvalidMergedSource} with no members or with more than one file-backed member.\n * @public\n */\nexport function merge(...members: Source[]): Source {\n    if (members.length === 0) {\n        throw new EnvaptError(EnvaptErrorCodes.InvalidMergedSource, 'merge requires at least one source.');\n    }\n\n    const fileMembers = members.filter((m): m is FileCapableSource => m.supportsFiles === true);\n    if (fileMembers.length > 1) {\n        throw new EnvaptError(\n            EnvaptErrorCodes.InvalidMergedSource,\n            'merge accepts at most one filesystem-backed source, so the .env cascade and file APIs route to a single member.'\n        );\n    }\n\n    const readVars = (): Record<string, string> => {\n        const merged: Record<string, string> = {};\n        for (const m of members) Object.assign(merged, m.readVars());\n        return merged;\n    };\n\n    const fileMember = fileMembers[0];\n    if (!fileMember) return { readVars };\n\n    const fileCapable: FileCapableSource = {\n        readVars,\n        supportsFiles: true,\n        readFile: (path, encoding) => fileMember.readFile(path, encoding),\n        resolvePath: (baseDir, candidate) => fileMember.resolvePath(baseDir, candidate),\n        normalizeBaseDir: (value) => fileMember.normalizeBaseDir(value),\n        writeVars: (vars) => fileMember.writeVars(vars)\n    };\n    return fileCapable;\n}\n"],"mappings":"iDAUA,SAAgB,EAAM,GAAG,EAA2B,CAChD,GAAI,EAAQ,SAAW,EACnB,MAAM,IAAI,EAAA,IAAkD,qCAAqC,EAGrG,IAAM,EAAc,EAAQ,OAAQ,GAA8B,EAAE,gBAAkB,EAAI,EAC1F,GAAI,EAAY,OAAS,EACrB,MAAM,IAAI,EAAA,IAEN,iHACJ,EAGJ,IAAM,MAAyC,CAC3C,IAAM,EAAiC,CAAC,EACxC,IAAK,IAAM,KAAK,EAAS,OAAO,OAAO,EAAQ,EAAE,SAAS,CAAC,EAC3D,OAAO,CACX,EAEM,EAAa,EAAY,GAW/B,OAVK,EAUE,CAPH,WACA,cAAe,GACf,UAAW,EAAM,IAAa,EAAW,SAAS,EAAM,CAAQ,EAChE,aAAc,EAAS,IAAc,EAAW,YAAY,EAAS,CAAS,EAC9E,iBAAmB,GAAU,EAAW,iBAAiB,CAAK,EAC9D,UAAY,GAAS,EAAW,UAAU,CAAI,CAEjC,EAVO,CAAE,UAAS,CAWvC"}
+{"version":3,"file":"merge.mjs","names":[],"sources":["../../../src/sources/merge.ts"],"sourcesContent":["import { normalizeSource } from './normalizeSource';\nimport { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { BareSource, FileCapableSource, Source } from '../types';\n\n/**\n * Compose several sources into one, read last-wins. A later member's `readVars()` value overrides an\n * earlier member's for the same key. A member may be a `(key) => string | undefined` reader for a\n * source that reads one key at a time, and it fills a key missing from every snapshot. Bind the result\n * with `Envapter.useSource`. Throws {@link EnvaptErrorCodes.InvalidMergedSource} with no members or with\n * more than one file-backed member.\n * @public\n * @see {@link https://envapt.materwelon.dev/docs/sources#combining-sources}\n */\nexport function merge(...members: (Source | ((key: string) => string | undefined))[]): Source {\n    if (members.length === 0) {\n        throw new EnvaptError(EnvaptErrorCodes.InvalidMergedSource, 'merge requires at least one source.');\n    }\n\n    const sources = members.map(normalizeSource);\n\n    const fileMembers = sources.filter((m): m is FileCapableSource => m.supportsFiles === true);\n    if (fileMembers.length > 1) {\n        throw new EnvaptError(\n            EnvaptErrorCodes.InvalidMergedSource,\n            'merge accepts at most one filesystem-backed source, so the .env cascade and file APIs route to a single member.'\n        );\n    }\n\n    const readVars = (): Record<string, string> => {\n        const merged: Record<string, string> = {};\n        for (const m of sources) Object.assign(merged, m.readVars());\n        return merged;\n    };\n\n    const readers = sources.filter(\n        (m): m is Source & { readVar: (key: string) => string | undefined } => typeof m.readVar === 'function'\n    );\n    const readVar =\n        readers.length === 0\n            ? undefined\n            : (key: string): string | undefined => {\n                  // last reader that answers wins, so scan from the end and return the first defined value\n                  for (let i = readers.length - 1; i >= 0; i--) {\n                      const found = readers[i]?.readVar(key);\n                      if (found !== undefined) return found;\n                  }\n                  return undefined;\n              };\n\n    const fileMember = fileMembers[0];\n    if (!fileMember) {\n        const bare: BareSource = { readVars };\n        if (readVar) bare.readVar = readVar;\n        return bare;\n    }\n\n    const fileCapable: FileCapableSource = {\n        readVars,\n        supportsFiles: true,\n        readFile: (path, encoding) => fileMember.readFile(path, encoding),\n        resolvePath: (baseDir, candidate) => fileMember.resolvePath(baseDir, candidate),\n        normalizeBaseDir: (value) => fileMember.normalizeBaseDir(value),\n        writeVars: (vars) => fileMember.writeVars(vars)\n    };\n    if (readVar) fileCapable.readVar = readVar;\n    return fileCapable;\n}\n"],"mappings":"yGAcA,SAAgB,EAAM,GAAG,EAAqE,CAC1F,GAAI,EAAQ,SAAW,EACnB,MAAM,IAAI,EAAA,IAAkD,qCAAqC,EAGrG,IAAM,EAAU,EAAQ,IAAI,CAAe,EAErC,EAAc,EAAQ,OAAQ,GAA8B,EAAE,gBAAkB,EAAI,EAC1F,GAAI,EAAY,OAAS,EACrB,MAAM,IAAI,EAAA,IAEN,iHACJ,EAGJ,IAAM,MAAyC,CAC3C,IAAM,EAAiC,CAAC,EACxC,IAAK,IAAM,KAAK,EAAS,OAAO,OAAO,EAAQ,EAAE,SAAS,CAAC,EAC3D,OAAO,CACX,EAEM,EAAU,EAAQ,OACnB,GAAsE,OAAO,EAAE,SAAY,UAChG,EACM,EACF,EAAQ,SAAW,EACb,IAAA,GACC,GAAoC,CAEjC,IAAK,IAAI,EAAI,EAAQ,OAAS,EAAG,GAAK,EAAG,IAAK,CAC1C,IAAM,EAAQ,EAAQ,EAAE,EAAE,QAAQ,CAAG,EACrC,GAAI,IAAU,IAAA,GAAW,OAAO,CACpC,CAEJ,EAEJ,EAAa,EAAY,GAC/B,GAAI,CAAC,EAAY,CACb,IAAM,EAAmB,CAAE,UAAS,EAEpC,OADI,IAAS,EAAK,QAAU,GACrB,CACX,CAEA,IAAM,EAAiC,CACnC,WACA,cAAe,GACf,UAAW,EAAM,IAAa,EAAW,SAAS,EAAM,CAAQ,EAChE,aAAc,EAAS,IAAc,EAAW,YAAY,EAAS,CAAS,EAC9E,iBAAmB,GAAU,EAAW,iBAAiB,CAAK,EAC9D,UAAY,GAAS,EAAW,UAAU,CAAI,CAClD,EAEA,OADI,IAAS,EAAY,QAAU,GAC5B,CACX"}

package/dist/portable/sources/normalizeSource.mjs

@@ -0,0 +1,2 @@
+function e(e){return typeof e==`function`?{supportsFiles:!1,readVars:()=>({}),readVar:e}:e}export{e as normalizeSource};
+//# sourceMappingURL=normalizeSource.mjs.map

package/dist/portable/sources/normalizeSource.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeSource.mjs","names":[],"sources":["../../../src/sources/normalizeSource.ts"],"sourcesContent":["import type { Source } from '../types';\n\nexport function normalizeSource(source: Source | ((key: string) => string | undefined)): Source {\n    return typeof source === 'function' ? { supportsFiles: false, readVars: () => ({}), readVar: source } : source;\n}\n"],"mappings":"AAEA,SAAgB,EAAgB,EAAgE,CAC5F,OAAO,OAAO,GAAW,WAAa,CAAE,cAAe,GAAO,cAAiB,CAAC,GAAI,QAAS,CAAO,EAAI,CAC5G"}

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

@@ -12,16 +12,15 @@ declare const SCALAR: {
   readonly Regexp: "regexp";
   readonly Date: "date";
   readonly Time: "time";
+  readonly Port: "port";
+  readonly Email: "email";
 };
-/**
- * String tokens for every built-in scalar converter.
- * @public
- */
 type ConverterToken = (typeof SCALAR)[keyof typeof SCALAR];
 /**
  * Custom element converter for use inside {@link Converters.array}. Receives the trimmed,
  * non-empty raw string for one array slot and returns the parsed value.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/converters#custom-converters}
  */
 type CustomElementConverter<TReturn = unknown> = (raw: string) => TReturn;
 type ArrayElement = Exclude<ConverterToken, 'json' | 'regexp'> | CustomElementConverter;
@@ -30,11 +29,6 @@ interface ArrayOf<TElement extends ArrayElement = ArrayElement> {
   readonly of: TElement;
   readonly delimiter: string;
 }
-/**
- * Runtime type guard for tokens produced by {@link Converters.array}.
- * @internal
- */
-declare function isArrayOf(value: unknown): value is ArrayOf;
 type ArrayScalarElement = Exclude<ConverterToken, 'json' | 'regexp'>;
 declare function buildArrayConverter<TReturn>(opts: {
   of: CustomElementConverter<TReturn>;
@@ -61,6 +55,7 @@ declare function buildArrayConverter(opts?: {
  * ```
  *
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/converters#built-in-tokens}
  */
 declare const Converters: {
   readonly array: typeof buildArrayConverter;
@@ -76,7 +71,9 @@ declare const Converters: {
   readonly Regexp: "regexp";
   readonly Date: "date";
   readonly Time: "time";
+  readonly Port: "port";
+  readonly Email: "email";
 };
 //#endregion
-export { ArrayOf, ConverterToken, Converters, CustomElementConverter, isArrayOf };
+export { ArrayOf, ConverterToken, Converters, CustomElementConverter };
 //# sourceMappingURL=Converters.d.mts.map

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

@@ -18,6 +18,8 @@ declare class AdvancedMethods extends PrimitiveMethods {
    * Supports both scalar tokens (e.g. `Converters.Number`) and `ArrayOf<...>` tokens
    * produced by `Converters.array(...)`. The key can be a single name or an ordered list.
    * The first defined value wins.
+   * @see {@link https://envapt.materwelon.dev/docs/envapter#converters}
+   * @see {@link https://envapt.materwelon.dev/docs/converters#custom-converters}
    */
   static getUsing<TFallback extends TimeFallback | undefined = undefined>(key: EnvKeyInput, converter: 'time', fallback?: TFallback): ConditionalReturn<number, TFallback>;
   static getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(key: EnvKeyInput, converter: TConverter, fallback?: TFallback): AdvancedConverterReturn<TConverter, TFallback>;
@@ -31,6 +33,8 @@ declare class AdvancedMethods extends PrimitiveMethods {
   /**
    * Get an environment variable using a custom converter function.
    * Accepts a single key or an ordered list for automatic fallback.
+   * @see {@link https://envapt.materwelon.dev/docs/envapter#converters}
+   * @see {@link https://envapt.materwelon.dev/docs/converters#custom-converters}
    */
   static getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(key: EnvKeyInput, converter: ConverterFunction<TReturnType>, fallback?: TFallback): ConditionalReturn<TReturnType, TFallback>;
   /**
@@ -41,6 +45,8 @@ declare class AdvancedMethods extends PrimitiveMethods {
    * Read a required environment variable and convert it, throwing `MissingEnvValue` when the value
    * is missing or empty. Returns the non-undefined converter output. Accepts a built-in or `ArrayOf`
    * token, or a custom parser function. The key can be a single name or an ordered list.
+   * @see {@link https://envapt.materwelon.dev/docs/envapter#fail-fast-on-missing-values}
+   * @see {@link https://envapt.materwelon.dev/docs/converters#require-a-converted-value}
    */
   static getRequired<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, converter: TConverter): InferConverterReturnType<TConverter>;
   static getRequired<TReturnType>(key: EnvKeyInput, converter: ConverterFunction<TReturnType, string>): TReturnType;
@@ -56,6 +62,8 @@ declare class AdvancedMethods extends PrimitiveMethods {
    * `MissingEnvValue` listing them all. Pass a `casing` (`'camelCase'`, `'PascalCase'`, or
    * `'kebab-case'`) to rename the record keys, splitting on underscores, which assumes the
    * conventional SCREAMING_SNAKE env-var names. With no casing the keys stay as-is.
+   * @see {@link https://envapt.materwelon.dev/docs/envapter#fail-fast-on-missing-values}
+   * @see {@link https://envapt.materwelon.dev/docs/converters#require-a-converted-value}
    */
   static getRequiredAll<Spec extends RequiredSpec, Casing extends KeyCasing | undefined = undefined>(spec: Spec, casing?: Casing): { [K in keyof Spec as RecaseKey<K & string, Casing>]: InferSpecField<Spec[K]> };
   /**
@@ -76,6 +84,7 @@ declare class AdvancedMethods extends PrimitiveMethods {
    * import { z } from 'zod';
    * const port = Envapter.parse('PORT', z.coerce.number().min(1024).max(65535), 3000);
    * ```
+   * @see {@link https://envapt.materwelon.dev/docs/standard-schema#any-conformant-validator-or-none}
    */
   static parse<Schema extends StandardSchemaV1>(key: EnvKeyInput, schema: SchemaConstraint<Schema>, fallback?: InferSchemaOutput<Schema>): InferSchemaOutput<Schema>;
   /**

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

@@ -9,6 +9,7 @@ declare abstract class EnvapterBase {
   /**
    * Enable or disable strict mode. Default `false`. Setting refreshes the cache so
    * previously-cached converted values get re-evaluated under the new rule.
+   * @see {@link https://envapt.materwelon.dev/docs/strict-mode#what-strict-mode-changes}
    */
   static set strict(value: boolean);
   static get strict(): boolean;
@@ -16,6 +17,7 @@ declare abstract class EnvapterBase {
    * 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]`.
+   * @see {@link https://envapt.materwelon.dev/docs/configuration#debug-logging}
    */
   static set debug(level: DebugLevel);
   static get debug(): DebugLevel;
@@ -29,6 +31,7 @@ declare abstract class EnvapterBase {
    * Flipping `false → true` mirrors the existing tracked delta immediately (no cache
    * refresh). Flipping `true → false` is one-way: previously mirrored keys remain in
    * `process.env` until the process exits.
+   * @see {@link https://envapt.materwelon.dev/docs/configuration#mirroring-to-processenv}
    */
   static set syncProcessEnv(value: boolean);
   static get syncProcessEnv(): boolean;
@@ -37,6 +40,7 @@ declare abstract class EnvapterBase {
    * `envFileOptions`, `configureProfiles`, `resetProfiles`). `'warn'` (the default) warns once and
    * no-ops, `'throw'` throws {@link EnvaptError} `FileApiUnsupported`. The node build runs these
    * APIs normally and this value has no effect there.
+   * @see {@link https://envapt.materwelon.dev/docs/compatibility#binding-by-runtime}
    */
   static set fileApiMode(mode: FileApiMode);
   static get fileApiMode(): FileApiMode;
@@ -44,16 +48,20 @@ declare abstract class EnvapterBase {
    * Eagerly load the `.env` cascade now instead of lazily on the first read. Idempotent: a no-op
    * once the cache is built. Useful before mirroring to `process.env` (see {@link syncProcessEnv}),
    * which is what the `envapt/config` side-effect entry does.
+   * @see {@link https://envapt.materwelon.dev/docs/configuration#which-files-load}
    */
   static load(): void;
   /**
    * Bind the environment {@link Source}. On Node the entry binds {@link FileSource} for you
    * (a `process.env` snapshot plus the `.env` cascade). On the browser or Workers, pass a
-   * `PortableSource` (or any `Source`) before reading. Clears and rebuilds the cache.
+   * `PortableSource` (or any `Source`) before reading. Pass a `(key) => string | undefined` reader for
+   * a source that reads one key at a time and cannot list its keys. Clears and rebuilds the cache.
+   * @see {@link https://envapt.materwelon.dev/docs/sources#the-providers}
    */
-  static useSource(source: Source): void;
+  static useSource(source: Source | ((key: string) => string | undefined)): void;
   /**
    * Read an environment variable as its raw string, skipping parsing and conversion.
+   * @see {@link https://envapt.materwelon.dev/docs/envapter#raw-values}
    */
   getRaw(key: EnvKeyInput): string | undefined;
 }

package/dist/types/core/Environment.d.mts

@@ -2,13 +2,14 @@
 /**
  * Environment types supported by Envapter
  *
- * The following keys are checked in order until the first with a non-empty value is found, or defaulting to development if none are set:
+ * The following keys are checked in order until the first with a present (non-missing) value, defaulting to development if none are set:
  * - `ENVIRONMENT`
  * - `ENV`
  * - `NODE_ENV`
  * - `MODE`
  *
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/environment#detecting-the-environment}
  */
 declare enum Environment {
   /** The default when no environment variable names a known environment. */

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

@@ -9,10 +9,12 @@ import { EnvapterBase } from "./EnvapterBase.mjs";
 declare class EnvironmentMethods extends EnvapterBase {
   /**
    * Get the current application environment
+   * @see {@link https://envapt.materwelon.dev/docs/environment#detecting-the-environment}
    */
   static get environment(): Environment;
   /**
    * Set the application environment. Accepts either Environment enum or string value.
+   * @see {@link https://envapt.materwelon.dev/docs/environment#detecting-the-environment}
    */
   static set environment(env: string | Environment);
   /**
@@ -25,6 +27,7 @@ declare class EnvironmentMethods extends EnvapterBase {
   set environment(env: string | Environment);
   /**
    * Check if the current environment is production
+   * @see {@link https://envapt.materwelon.dev/docs/environment#branching-on-the-environment}
    */
   static get isProduction(): boolean;
   /**
@@ -33,6 +36,7 @@ declare class EnvironmentMethods extends EnvapterBase {
   get isProduction(): boolean;
   /**
    * Check if the current environment is staging
+   * @see {@link https://envapt.materwelon.dev/docs/environment#branching-on-the-environment}
    */
   static get isStaging(): boolean;
   /**
@@ -41,6 +45,7 @@ declare class EnvironmentMethods extends EnvapterBase {
   get isStaging(): boolean;
   /**
    * Check if the current environment is development
+   * @see {@link https://envapt.materwelon.dev/docs/environment#branching-on-the-environment}
    */
   static get isDevelopment(): boolean;
   /**
@@ -49,6 +54,7 @@ declare class EnvironmentMethods extends EnvapterBase {
   get isDevelopment(): boolean;
   /**
    * Check if the current environment is test
+   * @see {@link https://envapt.materwelon.dev/docs/environment#branching-on-the-environment}
    */
   static get isTest(): boolean;
   /**

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

@@ -11,6 +11,7 @@ declare class PrimitiveMethods extends EnvironmentMethods {
    * Get a string environment variable with optional fallback.
    * Supports template variable resolution using `${VAR}` syntax.
    * Accepts a single key or an ordered array of keys (first match wins).
+   * @see {@link https://envapt.materwelon.dev/docs/envapter#primitives}
    */
   static get<Default extends string | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<string, Default>;
   /**
@@ -21,6 +22,7 @@ declare class PrimitiveMethods extends EnvironmentMethods {
    * Get a number environment variable with optional fallback.
    * Automatically converts string values to numbers.
    * Accepts a single key or an ordered array of keys (first match wins).
+   * @see {@link https://envapt.materwelon.dev/docs/envapter#primitives}
    */
   static getNumber<Default extends number | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<number, Default>;
   /**
@@ -31,6 +33,7 @@ declare class PrimitiveMethods extends EnvironmentMethods {
    * Get a boolean environment variable with optional fallback.
    * Recognizes: `1`, `yes`, `true`, `on` as **true**; `0`, `no`, `false`, `off` as **false** (case-insensitive).
    * Accepts a single key or an ordered array of keys (first match wins).
+   * @see {@link https://envapt.materwelon.dev/docs/envapter#primitives}
    */
   static getBoolean<Default extends boolean | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<boolean, Default>;
   /**
@@ -41,6 +44,7 @@ declare class PrimitiveMethods extends EnvironmentMethods {
    * Get a bigint environment variable with optional fallback.
    * Automatically converts string values to bigint.
    * Accepts a single key or an ordered array of keys (first match wins).
+   * @see {@link https://envapt.materwelon.dev/docs/envapter#primitives}
    */
   static getBigInt<Default extends bigint | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<bigint, Default>;
   /**
@@ -51,6 +55,7 @@ declare class PrimitiveMethods extends EnvironmentMethods {
    * Get a symbol environment variable with optional fallback.
    * Creates a symbol from the string value.
    * Accepts a single key or an ordered array of keys (first match wins).
+   * @see {@link https://envapt.materwelon.dev/docs/envapter#primitives}
    */
   static getSymbol<Default extends symbol | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<symbol, Default>;
   /**

package/dist/types/decorators/legacy/SugarDecorators.d.mts

@@ -6,18 +6,21 @@ import { EnvaptFieldDecorator } from "../../types/Decorator.mjs";
 /**
  * Shorthand for `@Envapt(key, { converter: Converters.Boolean, fallback })`.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/decorators#shorthand-decorators}
  */
 declare function EnvBool(key: EnvKeyInput, fallback: boolean): EnvaptFieldDecorator<boolean>;
 declare function EnvBool(key: EnvKeyInput): EnvaptFieldDecorator<boolean | null>;
 /**
  * Shorthand for `@Envapt(key, { converter: Converters.Number, fallback })`.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/decorators#shorthand-decorators}
  */
 declare function EnvNum(key: EnvKeyInput, fallback: number): EnvaptFieldDecorator<number>;
 declare function EnvNum(key: EnvKeyInput): EnvaptFieldDecorator<number | null>;
 /**
  * Shorthand for `@Envapt(key, { converter: Converters.String, fallback })`.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/decorators#shorthand-decorators}
  */
 declare function EnvStr(key: EnvKeyInput, fallback: string): EnvaptFieldDecorator<string>;
 declare function EnvStr(key: EnvKeyInput): EnvaptFieldDecorator<string | null>;
@@ -25,6 +28,7 @@ declare function EnvStr(key: EnvKeyInput): EnvaptFieldDecorator<string | null>;
  * Shorthand for `@Envapt(key, { converter: Converters.Time, fallback })`. The fallback is a
  * millisecond number or a time string (`'15m'`), and the resolved value is always milliseconds.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/decorators#shorthand-decorators}
  */
 declare function EnvTime(key: EnvKeyInput, fallback: TimeFallback): EnvaptFieldDecorator<number>;
 declare function EnvTime(key: EnvKeyInput): EnvaptFieldDecorator<number | null>;
@@ -32,6 +36,7 @@ declare function EnvTime(key: EnvKeyInput): EnvaptFieldDecorator<number | null>;
  * Shorthand for `@Envapt(key, { converter: Converters.Url, fallback })`. The fallback is a `URL`
  * instance, not a URL string.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/decorators#shorthand-decorators}
  */
 declare function EnvUrl(key: EnvKeyInput, fallback: URL): EnvaptFieldDecorator<URL>;
 declare function EnvUrl(key: EnvKeyInput): EnvaptFieldDecorator<URL | null>;

package/dist/types/decorators/modern/SugarDecorators.d.mts

@@ -6,18 +6,21 @@ import { EnvaptAccessorDecorator } from "../../types/Decorator.mjs";
 /**
  * Shorthand for `@Envapt(key, { converter: Converters.Boolean, fallback })`.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/decorators#shorthand-decorators}
  */
 declare function EnvBool(key: EnvKeyInput, fallback: boolean): EnvaptAccessorDecorator<boolean>;
 declare function EnvBool(key: EnvKeyInput): EnvaptAccessorDecorator<boolean | null>;
 /**
  * Shorthand for `@Envapt(key, { converter: Converters.Number, fallback })`.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/decorators#shorthand-decorators}
  */
 declare function EnvNum(key: EnvKeyInput, fallback: number): EnvaptAccessorDecorator<number>;
 declare function EnvNum(key: EnvKeyInput): EnvaptAccessorDecorator<number | null>;
 /**
  * Shorthand for `@Envapt(key, { converter: Converters.String, fallback })`.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/decorators#shorthand-decorators}
  */
 declare function EnvStr(key: EnvKeyInput, fallback: string): EnvaptAccessorDecorator<string>;
 declare function EnvStr(key: EnvKeyInput): EnvaptAccessorDecorator<string | null>;
@@ -25,6 +28,7 @@ declare function EnvStr(key: EnvKeyInput): EnvaptAccessorDecorator<string | null
  * Shorthand for `@Envapt(key, { converter: Converters.Time, fallback })`. The fallback is a
  * millisecond number or a time string (`'15m'`), and the resolved value is always milliseconds.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/decorators#shorthand-decorators}
  */
 declare function EnvTime(key: EnvKeyInput, fallback: TimeFallback): EnvaptAccessorDecorator<number>;
 declare function EnvTime(key: EnvKeyInput): EnvaptAccessorDecorator<number | null>;
@@ -32,6 +36,7 @@ declare function EnvTime(key: EnvKeyInput): EnvaptAccessorDecorator<number | nul
  * Shorthand for `@Envapt(key, { converter: Converters.Url, fallback })`. The fallback is a `URL`
  * instance, not a URL string.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/decorators#shorthand-decorators}
  */
 declare function EnvUrl(key: EnvKeyInput, fallback: URL): EnvaptAccessorDecorator<URL>;
 declare function EnvUrl(key: EnvKeyInput): EnvaptAccessorDecorator<URL | null>;

package/dist/types/engine/Envapter.d.mts

@@ -40,6 +40,7 @@ declare class Envapter extends AdvancedMethods {
    * const message = Envapter.resolve`Service endpoint: ${'API_URL'}`;
    * // Returns: "Service endpoint: https://api.example.com:8080"
    * ```
+   * @see {@link https://envapt.materwelon.dev/docs/templates#the-resolve-tagged-template}
    */
   static resolve(strings: TemplateStringsArray, ...keys: string[]): string;
   /**
@@ -47,8 +48,9 @@ declare class Envapter extends AdvancedMethods {
    */
   resolve(strings: TemplateStringsArray, ...keys: string[]): string;
   /**
-   * Assert that one or more environment variables are present and non-empty (post-trim,
-   * after template resolution). Throws `MissingEnvValue` listing every missing key.
+   * Assert that one or more environment variables are present and non-empty after template
+   * resolution. Throws `MissingEnvValue` listing every missing key. A whitespace-only value
+   * counts as missing only under strict mode.
    *
    * For a typed required read in functional code, use `Envapter.getRequired(key, converter)`.
    *

package/dist/types/engine/NodeEnvapter.d.mts

@@ -17,10 +17,12 @@ declare class NodeEnvapter extends Envapter {
    *
    * When set, this takes absolute precedence. The dotenv-flow auto-cascade and any
    * `Envapter.configureProfiles` configuration are ignored.
+   * @see {@link https://envapt.materwelon.dev/docs/configuration#which-files-load}
    */
   static set envPaths(paths: string[] | string);
   /**
    * Get currently configured .env file paths
+   * @see {@link https://envapt.materwelon.dev/docs/configuration#which-files-load}
    */
   static get envPaths(): string[];
   /**
@@ -32,14 +34,22 @@ declare class NodeEnvapter extends Envapter {
    *
    * Set this before `envPaths` so relative `envPaths` validate against the right directory.
    * Unset (`undefined`) restores `process.cwd()` resolution.
+   * @see {@link https://envapt.materwelon.dev/docs/configuration#reading-from-a-fixed-directory}
    */
   static set baseDir(value: string | URL | undefined);
-  /** The configured base directory, or `undefined` when relative paths resolve against the working directory. */
+  /**
+   * The configured base directory, or `undefined` when relative paths resolve against the working directory.
+   * @see {@link https://envapt.materwelon.dev/docs/configuration#reading-from-a-fixed-directory}
+   */
   static get baseDir(): string | undefined;
-  /** Set the env file loader options (`encoding`, `override`). Refreshes the cache. */
+  /**
+   * Set the env file loader options (`encoding`, `override`). Refreshes the cache.
+   * @see {@link https://envapt.materwelon.dev/docs/configuration#which-files-load}
+   */
   static set envFileOptions(config: EnvFileOptions);
   /**
    * Get current env file loader options
+   * @see {@link https://envapt.materwelon.dev/docs/configuration#which-files-load}
    */
   static get envFileOptions(): EnvFileOptions;
   /**
@@ -58,12 +68,14 @@ declare class NodeEnvapter extends Envapter {
    *   [Environment.Production]: { paths: ['config/prod.env', 'secrets/prod.env'] }
    * });
    * ```
+   * @see {@link https://envapt.materwelon.dev/docs/environment#custom-profiles}
    */
   static configureProfiles(config: ProfilesConfig): void;
   /**
    * Reset all path-resolution configuration to defaults: clears any prior
    * `Envapter.configureProfiles` call AND any explicit `Envapter.envPaths` assignment.
    * Returns the resolver to the pure dotenv-flow cascade.
+   * @see {@link https://envapt.materwelon.dev/docs/environment#custom-profiles}
    */
   static resetProfiles(): void;
 }

package/dist/types/index.d.mts

@@ -1,7 +1,7 @@
 import { Environment } from "./core/Environment.mjs";
 import { DebugLevel } from "./infra/Debug.mjs";
-import { ConverterToken, Converters, CustomElementConverter, isArrayOf } from "./converters/Converters.mjs";
-import { ConverterFunction, EnvaptConverter, JsonValue, TimeFallback } from "./types/Conversion.mjs";
+import { Converters, CustomElementConverter } from "./converters/Converters.mjs";
+import { ConverterFunction, JsonValue, TimeFallback } from "./types/Conversion.mjs";
 import { StandardSchemaV1 } from "./infra/StandardSchema.mjs";
 import { EnvProfile, EnvaptOptions, FileApiMode, ProfilesConfig } from "./types/Options.mjs";
 import { Source } from "./types/Source.mjs";
@@ -13,4 +13,4 @@ import { Envapt } from "./decorators/modern/Envapt.mjs";
 import { EnvBool, EnvNum, EnvStr, EnvTime, EnvUrl } from "./decorators/modern/SugarDecorators.mjs";
 import { NodeEnvapter } from "./engine/NodeEnvapter.mjs";
 import { FileSource } from "./sources/FileSource.mjs";
-export { type ConverterFunction, type ConverterToken, Converters, type CustomElementConverter, type DebugLevel, EnvBool, type EnvFileOptions, EnvNum, type EnvProfile, EnvStr, EnvTime, EnvUrl, Envapt, type EnvaptConverter, EnvaptError, EnvaptErrorCodes, type EnvaptOptions, NodeEnvapter as Envapter, Environment, type FileApiMode, FileSource, type JsonValue, PortableSource, type ProfilesConfig, type Source, type StandardSchemaV1, type TimeFallback, isArrayOf, merge };
+export { type ConverterFunction, Converters, type CustomElementConverter, type DebugLevel, EnvBool, type EnvFileOptions, EnvNum, type EnvProfile, EnvStr, EnvTime, EnvUrl, Envapt, EnvaptError, EnvaptErrorCodes, type EnvaptOptions, NodeEnvapter as Envapter, Environment, type FileApiMode, FileSource, type JsonValue, PortableSource, type ProfilesConfig, type Source, type StandardSchemaV1, type TimeFallback, merge };

package/dist/types/index.portable.d.mts

@@ -1,7 +1,7 @@
 import { Environment } from "./core/Environment.mjs";
 import { DebugLevel } from "./infra/Debug.mjs";
-import { ConverterToken, Converters, CustomElementConverter, isArrayOf } from "./converters/Converters.mjs";
-import { ConverterFunction, EnvaptConverter, JsonValue, TimeFallback } from "./types/Conversion.mjs";
+import { Converters, CustomElementConverter } from "./converters/Converters.mjs";
+import { ConverterFunction, JsonValue, TimeFallback } from "./types/Conversion.mjs";
 import { StandardSchemaV1 } from "./infra/StandardSchema.mjs";
 import { EnvProfile, EnvaptOptions, FileApiMode, ProfilesConfig } from "./types/Options.mjs";
 import { Source } from "./types/Source.mjs";
@@ -12,4 +12,4 @@ import { EnvaptError, EnvaptErrorCodes } from "./infra/Error.mjs";
 import { Envapt } from "./decorators/modern/Envapt.mjs";
 import { EnvBool, EnvNum, EnvStr, EnvTime, EnvUrl } from "./decorators/modern/SugarDecorators.mjs";
 import { PortableEnvapter } from "./engine/PortableEnvapter.mjs";
-export { type ConverterFunction, type ConverterToken, Converters, type CustomElementConverter, type DebugLevel, EnvBool, type EnvFileOptions, EnvNum, type EnvProfile, EnvStr, EnvTime, EnvUrl, Envapt, type EnvaptConverter, EnvaptError, EnvaptErrorCodes, type EnvaptOptions, PortableEnvapter as Envapter, Environment, type FileApiMode, type JsonValue, PortableSource, type ProfilesConfig, type Source, type StandardSchemaV1, type TimeFallback, isArrayOf, merge };
+export { type ConverterFunction, Converters, type CustomElementConverter, type DebugLevel, EnvBool, type EnvFileOptions, EnvNum, type EnvProfile, EnvStr, EnvTime, EnvUrl, Envapt, EnvaptError, EnvaptErrorCodes, type EnvaptOptions, PortableEnvapter as Envapter, Environment, type FileApiMode, type JsonValue, PortableSource, type ProfilesConfig, type Source, type StandardSchemaV1, type TimeFallback, merge };

package/dist/types/infra/Debug.d.mts

@@ -6,6 +6,7 @@
  * (whether it returns a fallback or `undefined`). `verbose` adds every loaded file,
  * per-file key count, per-key load lines, and effective-paths / cache-rebuild notices.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/configuration#debug-logging}
  */
 type DebugLevel = 'silent' | 'warn' | 'verbose';
 //#endregion

package/dist/types/infra/Dotenv.d.mts

@@ -5,6 +5,7 @@
  * For debug output, use `Envapter.debug` (or the `ENVAPT_DEBUG` env var).
  *
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/configuration#which-files-load}
  */
 interface EnvFileOptions {
   /** Encoding for reading .env files. Defaults to 'utf8'. */

package/dist/types/infra/Error.d.mts

@@ -4,6 +4,7 @@ import { StandardSchemaV1 } from "./StandardSchema.mjs";
 /**
  * Numeric codes carried by {@link EnvaptError.code}, grouped by fallback (1xx), converter (2xx),
  * and configuration (3xx) failures.
+ * @see {@link https://envapt.materwelon.dev/docs/errors#codes}
  */
 declare enum EnvaptErrorCodes {
   /** Thrown when an invalid fallback value is provided */
@@ -62,6 +63,7 @@ interface EnvaptErrorOptions {
  * ```ts
  * throw new EnvaptError(EnvaptErrorCodes.InvalidFallback, "Invalid fallback value provided for environment variable.");
  * ```
+ * @see {@link https://envapt.materwelon.dev/docs/errors#the-error-shape}
  */
 declare class EnvaptError extends Error {
   /** The {@link EnvaptErrorCodes} value identifying what failed. */

package/dist/types/infra/StandardSchema.d.mts

@@ -9,6 +9,7 @@
  * `SchemaMustBeSync` brand in `Types.ts`) and at runtime by the Parser dispatch.
  *
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/standard-schema#any-conformant-validator-or-none}
  */
 interface StandardSchemaV1<Input = unknown, Output = Input> {
   /** The Standard Schema entry point holding the validator and the inferred input/output types. */

package/dist/types/sources/FileSource.d.mts

@@ -6,6 +6,7 @@ import { FileCapableSource } from "../types/Source.mjs";
  * `supportsFiles` is `true`, so the engine also layers the `.env` cascade on top, resolves
  * `baseDir`, and can mirror loaded keys back to `process.env`.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/sources#the-providers}
  */
 declare class FileSource implements FileCapableSource {
   /** Always `true`. The engine layers the `.env` cascade and `baseDir` on top of `process.env`. */

package/dist/types/sources/PortableSource.d.mts

@@ -9,6 +9,7 @@ import { BareSource } from "../types/Source.mjs";
  * still apply, which means they must be JSON-serializable. Without a filesystem the `.env` cascade and
  * file APIs do not apply.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/sources#the-providers}
  */
 declare class PortableSource implements BareSource {
   /** Always `false`. With no filesystem, the `.env` cascade and file APIs do not apply. */

package/dist/types/sources/merge.d.mts

@@ -2,12 +2,15 @@ import { Source } from "../types/Source.mjs";
 
 //#region src/sources/merge.d.ts
 /**
- * Compose several sources into one, read last-wins. A later member's value overrides an earlier
- * member's value for the same key. Bind the result with `Envapter.useSource`. Throws
- * {@link EnvaptErrorCodes.InvalidMergedSource} with no members or with more than one file-backed member.
+ * Compose several sources into one, read last-wins. A later member's `readVars()` value overrides an
+ * earlier member's for the same key. A member may be a `(key) => string | undefined` reader for a
+ * source that reads one key at a time, and it fills a key missing from every snapshot. Bind the result
+ * with `Envapter.useSource`. Throws {@link EnvaptErrorCodes.InvalidMergedSource} with no members or with
+ * more than one file-backed member.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/sources#combining-sources}
  */
-declare function merge(...members: Source[]): Source;
+declare function merge(...members: (Source | ((key: string) => string | undefined))[]): Source;
 //#endregion
 export { merge };
 //# sourceMappingURL=merge.d.mts.map

package/dist/types/types/Conversion.d.mts

@@ -11,13 +11,9 @@ type BaseInput = string | undefined;
  * @param fallback - Fallback value when parsing is skipped
  * @returns Parsed value of type `TFallback`
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/converters#custom-converters}
  */
 type ConverterFunction<TFallback = unknown, TRaw extends BaseInput = BaseInput> = (raw: TRaw, fallback?: TFallback) => TFallback;
-/**
- * Environment variable converter: a primitive constructor, a built-in scalar token, an `ArrayOf<...>`
- * produced by {@link Converters.array}, or a custom parser function.
- * @public
- */
 type EnvaptConverter<TFallback> = PrimitiveConstructor | BuiltInConverter | ArrayOf | ConverterFunction<TFallback>;
 type JsonPrimitive = string | number | boolean | null;
 type JsonArray = JsonValue[];
@@ -27,6 +23,7 @@ interface JsonObject {
 /**
  * JSON value types for custom converters
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/converters#json}
  */
 type JsonValue = JsonPrimitive | JsonArray | JsonObject;
 interface ConverterMap {
@@ -42,6 +39,8 @@ interface ConverterMap {
   regexp: RegExp;
   date: Date;
   time: number;
+  port: number;
+  email: string;
 }
 type BuiltInConverterReturnType<ConverterKey extends BuiltInConverter> = ConverterMap[ConverterKey];
 /**
@@ -52,6 +51,7 @@ type TimeUnit = 'ms' | 's' | 'm' | 'h' | 'd' | 'w';
 /**
  * Fallback type for time duration conversions
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/converters#time-and-durations}
  */
 type TimeFallback = number | `${number}${TimeUnit}`;
 type ConditionalReturn<ReturnType, TFallback> = TFallback extends undefined ? ReturnType | undefined : ReturnType;

package/dist/types/types/Options.d.mts

@@ -6,6 +6,7 @@ import { EnvaptConverter } from "./Conversion.mjs";
  * Options for the \@Envapt decorator (modern API). `required: true` is mutually exclusive
  * with `fallback`; see the per-converter overloads in `Envapt.ts` for the type-level mutex.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/decorators#declaring-decorated-fields}
  */
 interface EnvaptOptions<TFallback = string> {
   /** Value returned when the variable is missing or empty. Mutually exclusive with `required: true`. */
@@ -18,6 +19,7 @@ interface EnvaptOptions<TFallback = string> {
 /**
  * Per-environment profile entry passed to `Envapter.configureProfiles`.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/environment#custom-profiles}
  */
 interface EnvProfile {
   /** One or more `.env` paths to load for this environment. Order matters: earlier paths take precedence. */
@@ -28,6 +30,7 @@ interface EnvProfile {
  * profile override. Unspecified environments fall through to the default cascade behavior
  * (`.env.${env}.local`, `.env.local`, `.env.${env}`, `.env`).
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/environment#custom-profiles}
  */
 type ProfilesConfig = Partial<Record<Environment, EnvProfile>> & {
   /**
@@ -42,6 +45,7 @@ type ProfilesConfig = Partial<Record<Environment, EnvProfile>> & {
  * warns once and no-ops, `'throw'` throws `FileApiUnsupported`. The node build runs these APIs
  * normally and is unaffected by this value.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/compatibility#binding-by-runtime}
  */
 type FileApiMode = 'warn' | 'throw';
 //#endregion