envapt 7.1.0 → 8.0.0-next.1

package/dist/portable/infra/runtime.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.mjs","names":[],"sources":["../../../src/infra/runtime.ts"],"sourcesContent":["import type { Source } from '../types';\n\n// importing Debug back into EnvapterBase would cycle, so the source and sink are injected via the setters below.\n/* v8 ignore start -- @preserve replaced at load on Node so the Node suite never runs these defaults */\nlet sink: (line: string) => void = (line) => {\n    // eslint-disable-next-line no-console -- the off-Node fallback log sink\n    console.error(line);\n};\nlet envReader: () => Record<string, string> = () => ({});\nlet varReader: ((key: string) => string | undefined) | undefined;\n/* v8 ignore stop */\n\nexport function setRuntimeSink(fn: (line: string) => void): void {\n    sink = fn;\n}\n\nexport function writeRuntimeLine(line: string): void {\n    sink(line);\n}\n\n// check snapshot first, then the source's per-key reader, so a reader source (empty snapshot) still resolves a key\nexport function readRuntimeVar(key: string): string | undefined {\n    const fromSnapshot = envReader()[key];\n    if (fromSnapshot !== undefined) return fromSnapshot;\n    // ENVAPT_DEBUG resolves through here, so a throwing reader must not abort the config load that triggered it\n    try {\n        return varReader?.(key);\n    } catch {\n        return undefined;\n    }\n}\n\nexport function bindRuntimeFromSource(source: Source): void {\n    envReader = (): Record<string, string> => source.readVars();\n    const readVar = source.readVar;\n    varReader = typeof readVar === 'function' ? readVar.bind(source) : undefined;\n}\n"],"mappings":"AAIA,IAAI,EAAgC,GAAS,CAEzC,QAAQ,MAAM,CAAI,CACtB,EACI,OAAiD,CAAC,GAClD,EAOJ,SAAgB,EAAiB,EAAoB,CACjD,EAAK,CAAI,CACb,CAGA,SAAgB,EAAe,EAAiC,CAC5D,IAAM,EAAe,EAAU,CAAC,CAAC,GACjC,GAAI,IAAiB,IAAA,GAAW,OAAO,EAEvC,GAAI,CACA,OAAO,IAAY,CAAG,CAC1B,MAAQ,CACJ,MACJ,CACJ,CAEA,SAAgB,EAAsB,EAAsB,CACxD,MAA0C,EAAO,SAAS,EAC1D,IAAM,EAAU,EAAO,QACvB,EAAY,OAAO,GAAY,WAAa,EAAQ,KAAK,CAAM,EAAI,IAAA,EACvE"}

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

@@ -0,0 +1 @@
+{"version":3,"file":"PortableSource.mjs","names":[],"sources":["../../../src/sources/PortableSource.ts"],"sourcesContent":["import { coerceToStringRecord } from './coerce';\n\nimport type { BareSource } from '../types';\n\n/**\n * Environment source seeded from an object you provide, for every runtime without a filesystem. The\n * config your bundler injects into a browser build (Vite's `import.meta.env`, a webpack `DefinePlugin`\n * global), the Cloudflare `env` binding, a Vercel Edge or Fastly config object, a test fixture, or any\n * plain object. Pass it straight through. Non-string values are JSON-stringified so the converters\n * still apply, which means they must be JSON-serializable. Without a filesystem the `.env` cascade and\n * file APIs do not apply.\n * @public\n * @see {@link https://envapt.materwelon.dev/docs/sources#the-providers}\n */\nexport class PortableSource implements BareSource {\n    /** Always `false`. With no filesystem, the `.env` cascade and file APIs do not apply. */\n    readonly supportsFiles = false;\n    private readonly vars: Record<string, string>;\n\n    /** Seed the source from `vars`. Non-string values are JSON-stringified so the converters still apply. */\n    constructor(vars: object) {\n        this.vars = coerceToStringRecord(vars);\n    }\n\n    /** Returns a snapshot clone of the provided object as plain strings. */\n    readVars(): Record<string, string> {\n        return { ...this.vars };\n    }\n}\n"],"mappings":"oDAcA,IAAa,EAAb,KAAkD,CAE9C,cAAyB,GACzB,KAGA,YAAY,EAAc,CACtB,KAAK,KAAO,EAAqB,CAAI,CACzC,CAGA,UAAmC,CAC/B,MAAO,CAAE,GAAG,KAAK,IAAK,CAC1B,CACJ"}

package/dist/{node/sources/UnboundEnvSource.mjs → portable/sources/UnboundSource.mjs}

@@ -1,2 +1,2 @@
-import{EnvaptError as e}from"../infra/Error.mjs";var t=class{supportsFiles=!1;readVars(){throw new e(307,`No environment source is bound. Call Envapter.useSource(...) with a source such as new PortableSource({...}) before reading.`)}};export{t as UnboundEnvSource};
-//# sourceMappingURL=UnboundEnvSource.mjs.map
+import{EnvaptError as e}from"../infra/Error.mjs";var t=class{supportsFiles=!1;readVars(){throw new e(307,`No environment source is bound. Call Envapter.useSource(...) with a source such as new PortableSource({...}) before reading.`)}};export{t as UnboundSource};
+//# sourceMappingURL=UnboundSource.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"UnboundSource.mjs","names":[],"sources":["../../../src/sources/UnboundSource.ts"],"sourcesContent":["import { EnvaptError, EnvaptErrorCodes } from '../infra/Error';\n\nimport type { BareSource } from '../types';\n\n/**\n * The default source until one is bound. Every read throws NoSourceBound so a forgotten `useSource`\n * surfaces at read time instead of silently yielding nothing. The Node entry binds {@link FileSource}\n * at load, browser and Workers bundles must call `Envapter.useSource(...)` before reading.\n * @internal\n */\nexport class UnboundSource implements BareSource {\n    readonly supportsFiles = false;\n\n    readVars(): Record<string, string> {\n        throw new EnvaptError(\n            EnvaptErrorCodes.NoSourceBound,\n            'No environment source is bound. Call Envapter.useSource(...) with a source such as new PortableSource({...}) before reading.'\n        );\n    }\n}\n"],"mappings":"iDAUA,IAAa,EAAb,KAAiD,CAC7C,cAAyB,GAEzB,UAAmC,CAC/B,MAAM,IAAI,EAAA,IAEN,8HACJ,CACJ,CACJ"}

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

@@ -0,0 +1 @@
+{"version":3,"file":"coerce.mjs","names":[],"sources":["../../../src/sources/coerce.ts"],"sourcesContent":["// The returned record is fresh, so a caller mutating its object\n// later cannot leak into the source, and non-string values are JSON-stringified.\nexport function coerceToStringRecord(env: object): Record<string, string> {\n    const snapshot: Record<string, string> = {};\n    // `object` so a Cloudflare `Env` (an interface with no index signature) is accepted. cast to a record\n    // to read entries as `unknown` rather than `any`.\n    for (const [key, value] of Object.entries(env as Record<string, unknown>)) {\n        if (typeof value === 'string') {\n            snapshot[key] = value;\n            continue;\n        }\n        const encoded = JSON.stringify(value);\n        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- TS lib mistypes JSON.stringify's return as always-string when it is string | undefined at runtime\n        if (encoded !== undefined) snapshot[key] = encoded;\n    }\n    return snapshot;\n}\n"],"mappings":"AAEA,SAAgB,EAAqB,EAAqC,CACtE,IAAM,EAAmC,CAAC,EAG1C,IAAK,GAAM,CAAC,EAAK,KAAU,OAAO,QAAQ,CAA8B,EAAG,CACvE,GAAI,OAAO,GAAU,SAAU,CAC3B,EAAS,GAAO,EAChB,QACJ,CACA,IAAM,EAAU,KAAK,UAAU,CAAK,EAEhC,IAAY,IAAA,KAAW,EAAS,GAAO,EAC/C,CACA,OAAO,CACX"}

package/dist/portable/sources/merge.mjs

@@ -0,0 +1,2 @@
+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

@@ -0,0 +1 @@
+{"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

@@ -13,42 +13,20 @@ declare const SCALAR: {
   readonly Date: "date";
   readonly Time: "time";
 };
-/**
- * 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;
-/**
- * Valid element converters for {@link Converters.array}: any scalar token except
- * `json` and `regexp` (those don't compose as array elements), or a custom function.
- * @public
- */
 type ArrayElement = Exclude<ConverterToken, 'json' | 'regexp'> | CustomElementConverter;
-/**
- * Phantom-branded token produced by {@link Converters.array}. The `T` type parameter carries
- * the element converter through any variable indirection so inference survives. The
- * `__envaptKind` discriminant is present at runtime for dispatch.
- * @public
- */
 interface ArrayOf<TElement extends ArrayElement = ArrayElement> {
-  /** Runtime discriminant marking this token as an array converter. Don't use directly. */
   readonly __envaptKind: 'array';
-  /** The element converter applied to each split slot. */
   readonly of: TElement;
-  /** The string the raw value is split on. */
   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>;
@@ -75,6 +53,7 @@ declare function buildArrayConverter(opts?: {
  * ```
  *
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/converters#built-in-tokens}
  */
 declare const Converters: {
   readonly array: typeof buildArrayConverter;
@@ -92,5 +71,5 @@ declare const Converters: {
   readonly Time: "time";
 };
 //#endregion
-export { ArrayElement, ArrayOf, ConverterToken, Converters, CustomElementConverter, isArrayOf };
+export { ArrayOf, ConverterToken, Converters, CustomElementConverter };
 //# sourceMappingURL=Converters.d.mts.map

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

@@ -1,19 +1,12 @@
 import { ArrayOf } from "../converters/Converters.mjs";
-import { AdvancedConverterReturn, BuiltInConverter, ConditionalReturn, ConverterFunction, InferConverterReturnType, TimeFallback } from "../types/Conversion.mjs";
+import { AdvancedConverterReturn, BuiltInConverter, ConditionalReturn, ConverterFunction, InferConverterReturnType, InferSpecField, RequiredSpec, TimeFallback } from "../types/Conversion.mjs";
+import { KeyCasing, RecaseKey } from "../types/Casing.mjs";
 import { InferSchemaOutput, StandardSchemaV1 } from "../infra/StandardSchema.mjs";
 import { SchemaConstraint } from "../types/Schema.mjs";
 import { EnvKeyInput } from "../types/Env.mjs";
 import { PrimitiveMethods } from "./PrimitiveMethods.mjs";
 
 //#region src/core/AdvancedMethods.d.ts
-interface GetUsingRequiredOptions<TConverter> {
-  converter: TConverter;
-  required: true;
-}
-interface GetWithRequiredOptions<TReturnType> {
-  converter: ConverterFunction<TReturnType>;
-  required: true;
-}
 /**
  * Mixin for advanced methods for environment variable conversion using built-in and custom converters
  * @internal
@@ -23,38 +16,65 @@ declare class AdvancedMethods extends PrimitiveMethods {
    * Get an environment variable using a built-in converter.
    *
    * 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.
+   * 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>;
   static getUsing<TReturn>(key: EnvKeyInput, converter: BuiltInConverter | ArrayOf, fallback?: TReturn): TReturn;
-  static getUsing(key: EnvKeyInput, options: GetUsingRequiredOptions<'time'>): number;
-  static getUsing<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, options: GetUsingRequiredOptions<TConverter>): InferConverterReturnType<TConverter>;
   /**
    * @see {@link AdvancedMethods.getUsing}
    */
   getUsing<TFallback extends TimeFallback | undefined = undefined>(key: EnvKeyInput, converter: 'time', fallback?: TFallback): ConditionalReturn<number, TFallback>;
   getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(key: EnvKeyInput, converter: TConverter, fallback?: TFallback): AdvancedConverterReturn<TConverter, TFallback>;
   getUsing<TReturn>(key: EnvKeyInput, converter: BuiltInConverter | ArrayOf, fallback?: TReturn): TReturn;
-  getUsing(key: EnvKeyInput, options: GetUsingRequiredOptions<'time'>): number;
-  getUsing<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, options: GetUsingRequiredOptions<TConverter>): InferConverterReturnType<TConverter>;
   /**
    * 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>;
-  static getWith<TReturnType>(key: EnvKeyInput, options: GetWithRequiredOptions<TReturnType>): TReturnType;
   /**
    * @see {@link AdvancedMethods.getWith}
    */
   getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(key: EnvKeyInput, converter: ConverterFunction<TReturnType>, fallback?: TFallback): ConditionalReturn<TReturnType, TFallback>;
-  getWith<TReturnType>(key: EnvKeyInput, options: GetWithRequiredOptions<TReturnType>): TReturnType;
+  /**
+   * 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;
+  /**
+   * @see {@link AdvancedMethods.getRequired}
+   */
+  getRequired<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, converter: TConverter): InferConverterReturnType<TConverter>;
+  getRequired<TReturnType>(key: EnvKeyInput, converter: ConverterFunction<TReturnType, string>): TReturnType;
+  /**
+   * Read a group of required environment variables in one call. Each key in `spec` maps to a
+   * converter (a token, an `array()` token, or a custom parser), and the returned record holds
+   * every converted value, all non-undefined. Collects every missing or empty key and throws one
+   * `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]> };
+  /**
+   * @see {@link AdvancedMethods.getRequiredAll}
+   */
+  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]> };
   /**
    * Validate an environment variable through a {@link StandardSchemaV1}-conformant schema
    * (zod, valibot, arktype, etc). Throws `MissingEnvValue` if the env value is absent and
-   * no fallback is provided. The fallback, when provided, is returned as-is on missing;
-   * it does NOT pass through the schema (mirrors custom-converter behavior).
+   * no fallback is provided. The fallback, when provided, is returned as-is on missing.
+   * It does NOT pass through the schema, mirroring custom-converter behavior.
    *
    * Synchronous schemas only. A Promise-returning `validate` triggers an
    * `InvalidUserDefinedConfig` throw at the call site.
@@ -64,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

@@ -1,22 +1,15 @@
 import { DebugLevel } from "../infra/Debug.mjs";
-import { EnvFileOptions } from "../infra/Dotenv.mjs";
+import { FileApiMode } from "../types/Options.mjs";
 import { EnvKeyInput } from "../types/Env.mjs";
-import { FileEnvSource, Source } from "../types/Source.mjs";
+import { Source } from "../types/Source.mjs";
 
 //#region src/core/EnvapterBase.d.ts
 /** @internal */
 declare abstract class EnvapterBase {
-  protected static _envPaths: string[];
-  protected static _envPathsExplicitlySet: boolean;
-  protected static _baseDir: string | undefined;
-  protected static _userDefinedEnvFileOptions: EnvFileOptions;
-  protected static _strict: boolean;
-  protected static _syncProcessEnv: boolean;
-  protected static _dotenvAddedKeys: Set<string>;
-  protected static _source: Source;
   /**
    * 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;
@@ -24,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;
@@ -37,36 +31,37 @@ 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;
-  protected static treatAsMissing(value: string | undefined): boolean;
-  protected static resolveAgainstBase(candidate: string): string;
-  protected static assertFileApiSupported(api: string, source: Source): asserts source is FileEnvSource;
-  protected static sourceFileExists(path: string): boolean;
-  protected static refreshCache(): void;
-  protected static mirrorToProcessEnv(): void;
-  protected static resolveForMirror(_key: string, value: string): string;
-  protected static resolveEffectivePaths(): string[];
-  protected static resolveKeyInput(keyInput: EnvKeyInput): {
-    key: string;
-    value: string | undefined;
-  };
-  protected static get config(): Map<string, unknown>;
+  /**
+   * On the portable build, this controls the filesystem-only config APIs (`envPaths`, `baseDir`,
+   * `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;
   /**
    * 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 NodeEnvSource} for you
+   * 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

@@ -0,0 +1,26 @@
+//#region src/core/Environment.d.ts
+/**
+ * Environment types supported by Envapter
+ *
+ * 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. */
+  Development = 0,
+  /** Selected when an environment variable reads `staging`. */
+  Staging = 1,
+  /** Selected when an environment variable reads `production`. */
+  Production = 2,
+  /** Selected when an environment variable reads `test`. */
+  Test = 3
+}
+//#endregion
+export { Environment };
+//# sourceMappingURL=Environment.d.mts.map

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

@@ -1,44 +1,20 @@
-import { ProfilesConfig } from "../types/Options.mjs";
+import { Environment } from "./Environment.mjs";
 import { EnvapterBase } from "./EnvapterBase.mjs";
 
 //#region src/core/EnvironmentMethods.d.ts
-/**
- * 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:
- * - `ENVIRONMENT`
- * - `ENV`
- * - `NODE_ENV`
- * - `MODE`
- *
- * @public
- */
-declare enum Environment {
-  /** The default when no environment variable names a known environment. */
-  Development = 0,
-  /** Selected when an environment variable reads `staging`. */
-  Staging = 1,
-  /** Selected when an environment variable reads `production`. */
-  Production = 2,
-  /** Selected when an environment variable reads `test`. */
-  Test = 3
-}
 /**
  * Mixin for environment detection and checking methods
  * @internal
  */
 declare class EnvironmentMethods extends EnvapterBase {
-  protected static _environment: Environment | undefined;
-  protected static _environmentExplicitlySet: boolean;
-  protected static _profiles: ProfilesConfig | undefined;
-  protected static determineEnvironment(env?: string | Environment): void;
-  private static firstEnvKeyValue;
   /**
    * 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);
   /**
@@ -51,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;
   /**
@@ -59,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;
   /**
@@ -67,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;
   /**
@@ -75,52 +54,14 @@ 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;
   /**
    * @see {@link EnvironmentMethods.isTest}
    */
   get isTest(): boolean;
-  protected static refreshCache(): void;
-  /**
-   * Reads the source's raw vars (not `this.config`, which would recurse: cascade selection runs
-   * before the `.env` load). `Envapter.environment` may differ post-load if a file sets `ENVIRONMENT`.
-   * @internal
-   */
-  protected static getCascadeEnvironment(): Environment;
-  /**
-   * Build the dotenv-flow cascade for a given environment, in dotenv first-wins precedence
-   * order (highest precedence first). Missing files are silently filtered.
-   *
-   * Precedence is **most-specific-wins** (matches Vite / Astro / Vocs):
-   *   `.env.${env}.local` \> `.env.${env}` \> `.env.local` \> `.env`
-   *
-   * This differs from dotenv-flow / Next.js convention which puts `.env.local` above
-   * `.env.${env}`. We chose the most-specific-wins order so committed env-specific files
-   * (`.env.production`) are authoritative for that environment regardless of whether a
-   * stray `.env.local` is present.
-   * @internal
-   */
-  protected static buildCascadePaths(env: Environment): string[];
-  private static normalizeProfilePaths;
-  /**
-   * Override the base implementation to layer the dotenv-flow cascade + any
-   * `Envapter.configureProfiles` overrides on top of `_envPaths` when the user has NOT
-   * explicitly set `envPaths`.
-   *
-   * Precedence (passed to dotenv with first-wins semantics):
-   *   1. profile-configured paths for the current env (if any)
-   *   2. `.env.${env}.local`
-   *   3. `.env.${env}`
-   *   4. `.env.local`
-   *   5. `.env`
-   *
-   * If `useDefaults: false` is set on the profiles config, only (1) is loaded, no cascade.
-   * If `envPaths` was explicitly set, only `envPaths` is loaded (everything else ignored).
-   * @internal
-   */
-  protected static resolveEffectivePaths(): string[];
 }
 //#endregion
-export { Environment, EnvironmentMethods };
+export { EnvironmentMethods };
 //# sourceMappingURL=EnvironmentMethods.d.mts.map

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

@@ -1,24 +1,17 @@
 import { ConditionalReturn } from "../types/Conversion.mjs";
+import { EnvKeyInput } from "../types/Env.mjs";
 import { EnvironmentMethods } from "./EnvironmentMethods.mjs";
-import { EnvKeyInput, EnvapterService } from "../types/Env.mjs";
-import { ValueConverter } from "../converters/ValueConverter.mjs";
-import { TemplateResolver } from "../engine/TemplateResolver.mjs";
 
 //#region src/core/PrimitiveMethods.d.ts
 /**
  * @internal
  */
-declare class PrimitiveMethods extends EnvironmentMethods implements EnvapterService {
-  private static readonly service;
-  protected static readonly templateResolver: TemplateResolver;
-  protected static readonly valueConverter: ValueConverter;
-  isStrict(): boolean;
-  protected static resolveForMirror(key: string, value: string): string;
-  private static _get;
+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>;
   /**
@@ -29,6 +22,7 @@ declare class PrimitiveMethods extends EnvironmentMethods implements EnvapterSer
    * 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>;
   /**
@@ -39,6 +33,7 @@ declare class PrimitiveMethods extends EnvironmentMethods implements EnvapterSer
    * 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>;
   /**
@@ -49,6 +44,7 @@ declare class PrimitiveMethods extends EnvironmentMethods implements EnvapterSer
    * 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>;
   /**
@@ -59,6 +55,7 @@ declare class PrimitiveMethods extends EnvironmentMethods implements EnvapterSer
    * 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

@@ -1,4 +1,4 @@
-import { Environment } from "../core/EnvironmentMethods.mjs";
+import { Environment } from "../core/Environment.mjs";
 import { AdvancedMethods } from "../core/AdvancedMethods.mjs";
 
 //#region src/engine/Envapter.d.ts
@@ -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,10 +48,11 @@ 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 typed fail-fast in functional code, use `Envapter.getUsing(key, { converter, required: true })`.
+   * For a typed required read in functional code, use `Envapter.getRequired(key, converter)`.
    *
    * @example
    * ```ts
@@ -59,7 +61,6 @@ declare class Envapter extends AdvancedMethods {
    * ```
    */
   static require(...keys: [string, ...string[]]): void;
-  private static resolveAndValidate;
   /**
    * @see {@link Envapter.require}
    */