envapt 7.1.0 → 8.0.0-next.0

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

@@ -1,38 +1,12 @@
-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
    */
@@ -81,46 +55,7 @@ declare class EnvironmentMethods extends EnvapterBase {
    * @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,20 +1,12 @@
 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.

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
@@ -50,7 +50,7 @@ declare class Envapter extends AdvancedMethods {
    * Assert that one or more environment variables are present and non-empty (post-trim,
    * after template resolution). Throws `MissingEnvValue` listing every missing key.
    *
-   * 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 +59,6 @@ declare class Envapter extends AdvancedMethods {
    * ```
    */
   static require(...keys: [string, ...string[]]): void;
-  private static resolveAndValidate;
   /**
    * @see {@link Envapter.require}
    */

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

@@ -1,16 +1,13 @@
-import { EnvFileOptions } from "../infra/Dotenv.mjs";
 import { ProfilesConfig } from "../types/Options.mjs";
 import { Envapter } from "./Envapter.mjs";
+import { EnvFileOptions } from "../infra/Dotenv.mjs";
 
 //#region src/engine/NodeEnvapter.d.ts
 /**
  * The Node/Bun/Deno facade: {@link Envapter} plus the filesystem-only configuration APIs (`.env`
- * path selection, base directory, dotenv options, and per-environment profiles). The browser and
- * Workers builds export the base {@link Envapter} without these, so calling one where there is no
- * filesystem is a compile error (and a thrown {@link EnvaptError} when types are bypassed).
- *
- * Writes target the state-owning class (`EnvapterBase`/`EnvironmentMethods`), not `this`: the engine
- * reads that state through `EnvapterBase`-anchored paths, so a subclass own-property would be invisible.
+ * path selection, base directory, dotenv options, and per-environment profiles). On the portable
+ * build (Workers, the browser, edge) these same APIs warn once and no-op by default, controlled by
+ * `Envapter.fileApiMode`.
  * @public
  */
 declare class NodeEnvapter extends Envapter {

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

@@ -1,14 +1,26 @@
+import { ProfilesConfig } from "../types/Options.mjs";
 import { Envapter } from "./Envapter.mjs";
+import { EnvFileOptions } from "../infra/Dotenv.mjs";
 
 //#region src/engine/PortableEnvapter.d.ts
 /**
- * The browser/Workers facade. {@link Envapter} with the filesystem-only configuration APIs
- * (`envPaths`, `baseDir`, `envFileOptions`, `configureProfiles`, `resetProfiles`) stubbed to throw
- * {@link EnvaptError}. The portable types omit those APIs, so the stubs only guard JS callers that
- * bypass the types.
+ * The browser/Workers/edge facade. {@link Envapter} with the filesystem-only config APIs present in
+ * the type but inert at runtime by default. Under the default `fileApiMode` of `'warn'` they warn once
+ * and no-op (getters return an empty default matching their type, setters do nothing). `'throw'` restores
+ * the {@link EnvaptError} `FileApiUnsupported`. The read side still throws `NoSourceBound` on first read
+ * until `useSource` binds a source.
  * @public
  */
-declare class PortableEnvapter extends Envapter {}
+declare class PortableEnvapter extends Envapter {
+  static get envPaths(): string[];
+  static set envPaths(_paths: string[] | string);
+  static get baseDir(): string | undefined;
+  static set baseDir(_value: string | URL | undefined);
+  static get envFileOptions(): EnvFileOptions;
+  static set envFileOptions(_config: EnvFileOptions);
+  static configureProfiles(_config: ProfilesConfig): void;
+  static resetProfiles(): void;
+}
 //#endregion
 export { PortableEnvapter };
 //# sourceMappingURL=PortableEnvapter.d.mts.map

package/dist/types/index.d.mts

@@ -1,20 +1,16 @@
+import { Environment } from "./core/Environment.mjs";
 import { DebugLevel } from "./infra/Debug.mjs";
-import { EnvFileOptions } from "./infra/Dotenv.mjs";
-import { ArrayElement, ArrayOf, ConverterToken, Converters, CustomElementConverter, isArrayOf } from "./converters/Converters.mjs";
-import { AdvancedConverterReturn, BuiltInConverter, BuiltInConverterFunction, ConditionalReturn, ConverterFunction, EnvaptConverter, InferConverterFallbackType, InferConverterReturnType, InferPrimitiveReturnType, JsonValue, MapOfConverterFunctions, PrimitiveConstructor, TimeFallback, TimeUnit } from "./types/Conversion.mjs";
-import { InferSchemaInput, InferSchemaOutput, StandardSchemaV1 } from "./infra/StandardSchema.mjs";
-import { Err, SchemaConstraint, SchemaMustBeSync } from "./types/Schema.mjs";
-import { Environment } from "./core/EnvironmentMethods.mjs";
-import { EnvProfile, EnvaptOptions, ProfilesConfig } from "./types/Options.mjs";
-import { EnvKeyInput } from "./types/Env.mjs";
-import { BareEnvSource, EnvSource, FileEnvSource, Source } from "./types/Source.mjs";
-import { EnvaptAccessorDecorator, EnvaptFieldDecorator } from "./types/Decorator.mjs";
+import { ConverterToken, Converters, CustomElementConverter, isArrayOf } from "./converters/Converters.mjs";
+import { ConverterFunction, EnvaptConverter, 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";
 import { PortableSource } from "./sources/PortableSource.mjs";
-import { ManualEnvSource } from "./sources/ManualEnvSource.mjs";
-import { WorkerEnvSource } from "./sources/WorkerEnvSource.mjs";
+import { merge } from "./sources/merge.mjs";
+import { EnvFileOptions } from "./infra/Dotenv.mjs";
 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 { NodeEnvapter } from "./engine/NodeEnvapter.mjs";
-import { NodeEnvSource } from "./sources/NodeEnvSource.mjs";
-export { type AdvancedConverterReturn, type ArrayElement, type ArrayOf, type BareEnvSource, type BuiltInConverter, type BuiltInConverterFunction, type ConditionalReturn, type ConverterFunction, type ConverterToken, Converters, type CustomElementConverter, type DebugLevel, EnvBool, type EnvFileOptions, type EnvKeyInput, EnvNum, type EnvProfile, type EnvSource, EnvStr, EnvTime, EnvUrl, Envapt, type EnvaptAccessorDecorator, type EnvaptConverter, EnvaptError, EnvaptErrorCodes, type EnvaptFieldDecorator, type EnvaptOptions, NodeEnvapter as Envapter, Environment, type Err, type FileEnvSource, type InferConverterFallbackType, type InferConverterReturnType, type InferPrimitiveReturnType, type InferSchemaInput, type InferSchemaOutput, type JsonValue, ManualEnvSource, type MapOfConverterFunctions, NodeEnvSource, PortableSource, type PrimitiveConstructor, type ProfilesConfig, type SchemaConstraint, type SchemaMustBeSync, type Source, type StandardSchemaV1, type TimeFallback, type TimeUnit, WorkerEnvSource, isArrayOf };
+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 };

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

@@ -1,19 +1,15 @@
+import { Environment } from "./core/Environment.mjs";
 import { DebugLevel } from "./infra/Debug.mjs";
-import { EnvFileOptions } from "./infra/Dotenv.mjs";
-import { ArrayElement, ArrayOf, ConverterToken, Converters, CustomElementConverter, isArrayOf } from "./converters/Converters.mjs";
-import { AdvancedConverterReturn, BuiltInConverter, BuiltInConverterFunction, ConditionalReturn, ConverterFunction, EnvaptConverter, InferConverterFallbackType, InferConverterReturnType, InferPrimitiveReturnType, JsonValue, MapOfConverterFunctions, PrimitiveConstructor, TimeFallback, TimeUnit } from "./types/Conversion.mjs";
-import { InferSchemaInput, InferSchemaOutput, StandardSchemaV1 } from "./infra/StandardSchema.mjs";
-import { Err, SchemaConstraint, SchemaMustBeSync } from "./types/Schema.mjs";
-import { Environment } from "./core/EnvironmentMethods.mjs";
-import { EnvProfile, EnvaptOptions, ProfilesConfig } from "./types/Options.mjs";
-import { EnvKeyInput } from "./types/Env.mjs";
-import { BareEnvSource, EnvSource, FileEnvSource, Source } from "./types/Source.mjs";
-import { EnvaptAccessorDecorator, EnvaptFieldDecorator } from "./types/Decorator.mjs";
+import { ConverterToken, Converters, CustomElementConverter, isArrayOf } from "./converters/Converters.mjs";
+import { ConverterFunction, EnvaptConverter, 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";
 import { PortableSource } from "./sources/PortableSource.mjs";
-import { ManualEnvSource } from "./sources/ManualEnvSource.mjs";
-import { WorkerEnvSource } from "./sources/WorkerEnvSource.mjs";
+import { merge } from "./sources/merge.mjs";
+import { EnvFileOptions } from "./infra/Dotenv.mjs";
 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 AdvancedConverterReturn, type ArrayElement, type ArrayOf, type BareEnvSource, type BuiltInConverter, type BuiltInConverterFunction, type ConditionalReturn, type ConverterFunction, type ConverterToken, Converters, type CustomElementConverter, type DebugLevel, EnvBool, type EnvFileOptions, type EnvKeyInput, EnvNum, type EnvProfile, type EnvSource, EnvStr, EnvTime, EnvUrl, Envapt, type EnvaptAccessorDecorator, type EnvaptConverter, EnvaptError, EnvaptErrorCodes, type EnvaptFieldDecorator, type EnvaptOptions, PortableEnvapter as Envapter, Environment, type Err, type FileEnvSource, type InferConverterFallbackType, type InferConverterReturnType, type InferPrimitiveReturnType, type InferSchemaInput, type InferSchemaOutput, type JsonValue, ManualEnvSource, type MapOfConverterFunctions, PortableSource, type PrimitiveConstructor, type ProfilesConfig, type SchemaConstraint, type SchemaMustBeSync, type Source, type StandardSchemaV1, type TimeFallback, type TimeUnit, WorkerEnvSource, isArrayOf };
+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 };

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

@@ -47,7 +47,9 @@ declare enum EnvaptErrorCodes {
   /** 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
+  NoSourceBound = 307,
+  /** Thrown when `merge` is called with no members, or with more than one filesystem-backed source */
+  InvalidMergedSource = 308
 }
 interface EnvaptErrorOptions {
   issues?: readonly StandardSchemaV1.Issue[];

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

@@ -43,18 +43,7 @@ declare namespace StandardSchemaV1 {
   type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
   type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
 }
-/**
- * Envapt-side alias for {@link StandardSchemaV1.InferOutput}. Re-exported under a friendlier
- * name so consumers writing `static readonly x: InferSchemaOutput<typeof mySchema>`
- * don't need the namespace path.
- * @public
- */
 type InferSchemaOutput<Schema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<Schema>;
-/**
- * Envapt-side alias for {@link StandardSchemaV1.InferInput}.
- * @public
- */
-type InferSchemaInput<Schema extends StandardSchemaV1> = StandardSchemaV1.InferInput<Schema>;
 //#endregion
-export { InferSchemaInput, InferSchemaOutput, StandardSchemaV1 };
+export { InferSchemaOutput, StandardSchemaV1 };
 //# sourceMappingURL=StandardSchema.d.mts.map

package/dist/types/sources/{NodeEnvSource.d.mts → FileSource.d.mts}

@@ -1,13 +1,13 @@
-import { FileEnvSource } from "../types/Source.mjs";
+import { FileCapableSource } from "../types/Source.mjs";
 
-//#region src/sources/NodeEnvSource.d.ts
+//#region src/sources/FileSource.d.ts
 /**
  * Default environment source on Node, Bun, and Deno: a snapshot of `process.env`. Its
  * `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
  */
-declare class NodeEnvSource implements FileEnvSource {
+declare class FileSource implements FileCapableSource {
   /** Always `true`. The engine layers the `.env` cascade and `baseDir` on top of `process.env`. */
   readonly supportsFiles = true;
   /** Returns a snapshot clone of `process.env` as plain strings. */
@@ -26,5 +26,5 @@ declare class NodeEnvSource implements FileEnvSource {
   writeVars(vars: Record<string, string>): void;
 }
 //#endregion
-export { NodeEnvSource };
-//# sourceMappingURL=NodeEnvSource.d.mts.map
+export { FileSource };
+//# sourceMappingURL=FileSource.d.mts.map

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

@@ -1,4 +1,4 @@
-import { BareEnvSource } from "../types/Source.mjs";
+import { BareSource } from "../types/Source.mjs";
 
 //#region src/sources/PortableSource.d.ts
 /**
@@ -10,7 +10,7 @@ import { BareEnvSource } from "../types/Source.mjs";
  * file APIs do not apply.
  * @public
  */
-declare class PortableSource implements BareEnvSource {
+declare class PortableSource implements BareSource {
   /** Always `false`. With no filesystem, the `.env` cascade and file APIs do not apply. */
   readonly supportsFiles = false;
   private readonly vars;

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

@@ -0,0 +1,13 @@
+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.
+ * @public
+ */
+declare function merge(...members: Source[]): Source;
+//#endregion
+export { merge };
+//# sourceMappingURL=merge.d.mts.map

package/dist/types/types/Casing.d.mts

@@ -0,0 +1,8 @@
+//#region src/types/Casing.d.ts
+type KeyCasing = 'camelCase' | 'PascalCase' | 'kebab-case';
+type SnakeToPascal<Str extends string> = Str extends `${infer Head}_${infer Tail}` ? `${Capitalize<Lowercase<Head>>}${SnakeToPascal<Tail>}` : Capitalize<Lowercase<Str>>;
+type SnakeToKebab<Str extends string, Acc extends string = ''> = Str extends `${infer Head}_${infer Tail}` ? SnakeToKebab<Tail, Head extends '' ? Acc : Acc extends '' ? Lowercase<Head> : `${Acc}-${Lowercase<Head>}`> : Str extends '' ? Acc : Acc extends '' ? Lowercase<Str> : `${Acc}-${Lowercase<Str>}`;
+type RecaseKey<Key extends string, Casing> = Casing extends 'camelCase' ? Uncapitalize<SnakeToPascal<Key>> : Casing extends 'PascalCase' ? SnakeToPascal<Key> : Casing extends 'kebab-case' ? SnakeToKebab<Key> : Key;
+//#endregion
+export type { KeyCasing, RecaseKey };
+//# sourceMappingURL=Casing.d.mts.map

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

@@ -1,30 +1,18 @@
 import { ArrayOf, ConverterToken, CustomElementConverter } from "../converters/Converters.mjs";
 
 //#region src/types/Conversion.d.ts
-/**
- * Scalar built-in converter tokens (e.g. `'number'`, `'time'`).
- * Excludes the array builder (see {@link ArrayOf}).
- * @public
- */
 type BuiltInConverter = ConverterToken;
-/**
- * Primitive types supported by Envapter
- * @public
- */
 type PrimitiveConstructor = typeof String | typeof Number | typeof Boolean | typeof BigInt | typeof Symbol;
-/**
- * String value from a .env file or environment variable
- * @public
- */
 type BaseInput = string | undefined;
 /**
- * Custom parser function type for environment variables
- * @param raw - Raw string value from environment
- * @param fallback - Fallback value if parsing fails
- * @returns Parsed value of type T
+ * Custom parser function for an environment variable. `TRaw` is the raw input, `string | undefined` by
+ * default, narrowed to `string` by the readers that guarantee a present value (`getRequired`, `getRequiredAll`).
+ * @param raw - Raw value from the environment
+ * @param fallback - Fallback value when parsing is skipped
+ * @returns Parsed value of type `TFallback`
  * @public
  */
-type ConverterFunction<TFallback = unknown> = (raw: BaseInput, fallback?: TFallback) => TFallback;
+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.
@@ -55,26 +43,7 @@ interface ConverterMap {
   date: Date;
   time: number;
 }
-/**
- * Type mapping for built-in scalar converters to their return types
- * @internal
- */
 type BuiltInConverterReturnType<ConverterKey extends BuiltInConverter> = ConverterMap[ConverterKey];
-/**
- * Return type for built-in converter functions
- * @internal
- */
-type ReturnValuesOfConverterFunctions = ConverterMap[BuiltInConverter];
-/**
- * Function type for built-in converter functions
- * @internal
- */
-type BuiltInConverterFunction = (...args: Parameters<(...args: any[]) => ReturnValuesOfConverterFunctions>) => ReturnValuesOfConverterFunctions | undefined;
-/**
- * Map of built-in converter functions
- * @internal
- */
-type MapOfConverterFunctions = Record<BuiltInConverter, BuiltInConverterFunction>;
 /**
  * Time unit types for duration conversions
  * @internal
@@ -85,39 +54,13 @@ type TimeUnit = 'ms' | 's' | 'm' | 'h' | 'd' | 'w';
  * @public
  */
 type TimeFallback = number | `${number}${TimeUnit}`;
-/**
- * Helper type for getter methods that conditionally return undefined based on whether a fallback is provided
- * If fallback is provided, return ReturnType. If no fallback (undefined), return ReturnType | undefined.
- * @internal
- */
 type ConditionalReturn<ReturnType, TFallback> = TFallback extends undefined ? ReturnType | undefined : ReturnType;
-/**
- * Inferred return type for a converter.
- *
- * - `ArrayOf<E>` resolves to the element type's return as an array. When `E` is a custom
- *   function, the function's return type drives the array element. When `E` is a scalar
- *   token, `ConverterMap` provides the element type.
- * - Bare scalar tokens resolve through `ConverterMap`.
- * @internal
- */
 type InferConverterReturnType<TConverter> = TConverter extends ArrayOf<infer Element> ? Element extends BuiltInConverter ? ConverterMap[Element][] : Element extends CustomElementConverter<infer Returned> ? Returned[] : never : TConverter extends BuiltInConverter ? BuiltInConverterReturnType<TConverter> : never;
-/**
- * Type inference for the *fallback* slot of a converter. `Converters.Time` (scalar or array
- * element) accepts {@link TimeFallback} / `TimeFallback[]`; everything else mirrors the
- * return type. Add future asymmetric fallback/return converters to this conditional.
- * @internal
- */
+type RequiredSpec = Record<string, BuiltInConverter | ArrayOf | ConverterFunction<unknown, string>>;
+type InferSpecField<TConverter> = TConverter extends BuiltInConverter | ArrayOf ? InferConverterReturnType<TConverter> : TConverter extends ((raw: string) => infer TReturn) ? TReturn : never;
 type InferConverterFallbackType<TConverter> = TConverter extends 'time' ? TimeFallback : TConverter extends ArrayOf<infer Element> ? Element extends 'time' ? TimeFallback[] : InferConverterReturnType<TConverter> : InferConverterReturnType<TConverter>;
-/**
- * Complete type inference for advanced converter methods
- * @internal
- */
 type AdvancedConverterReturn<TConverter, TFallback = undefined> = ConditionalReturn<InferConverterReturnType<TConverter>, TFallback>;
-/**
- * Type inference for primitive constructor return types
- * @internal
- */
 type InferPrimitiveReturnType<TConstructor extends PrimitiveConstructor> = TConstructor extends typeof String ? string : TConstructor extends typeof Number ? number : TConstructor extends typeof Boolean ? boolean : TConstructor extends typeof BigInt ? bigint : TConstructor extends typeof Symbol ? symbol : never;
 //#endregion
-export type { AdvancedConverterReturn, BuiltInConverter, BuiltInConverterFunction, ConditionalReturn, ConverterFunction, EnvaptConverter, InferConverterFallbackType, InferConverterReturnType, InferPrimitiveReturnType, JsonValue, MapOfConverterFunctions, PrimitiveConstructor, TimeFallback, TimeUnit };
+export type { AdvancedConverterReturn, BuiltInConverter, ConditionalReturn, ConverterFunction, EnvaptConverter, InferConverterFallbackType, InferConverterReturnType, InferPrimitiveReturnType, InferSpecField, JsonValue, PrimitiveConstructor, RequiredSpec, TimeFallback };
 //# sourceMappingURL=Conversion.d.mts.map

package/dist/types/types/Decorator.d.mts

@@ -1,21 +1,7 @@
 //#region src/types/Decorator.d.ts
-/**
- * A legacy (experimentalDecorators) property decorator that also constrains the decorated field's
- * declared type. `Output` is the value the decorator produces. The field must be wide enough to hold
- * it, so a field narrower than `Output` fails to compile while a wider or nullable field is accepted.
- * The tuple wrap stops `Output` from distributing when it is a union.
- * @public
- */
 type EnvaptFieldDecorator<Output> = <Target, Key extends keyof Target>(target: Target, key: [Output] extends [Target[Key]] ? Key : {
   '[envapt] field type must hold the converter output': Output;
 }) => void;
-/**
- * A modern (TC39 Stage 3) accessor decorator that also constrains the decorated `accessor`'s
- * declared type. `Output` is the value the decorator produces. The accessor must be wide enough to
- * hold it, so an accessor narrower than `Output` fails to compile while a wider or nullable one is
- * accepted. The tuple wrap stops `Output` from distributing when it is a union.
- * @public
- */
 type EnvaptAccessorDecorator<Output> = <This, Value>(target: ClassAccessorDecoratorTarget<This, [Output] extends [Value] ? Value : {
   '[envapt] field type must hold the converter output': Output;
 }>, context: ClassAccessorDecoratorContext<This, [Output] extends [Value] ? Value : {

package/dist/types/types/Env.d.mts

@@ -1,17 +1,8 @@
 //#region src/types/Env.d.ts
-/**
- * Accepted shape for environment variable lookups. Either a single key or an ordered list of keys.
- * @public
- */
 type EnvKeyInput = string | readonly [string, ...string[]];
 /**
  * @internal
  */
-interface EnvapterService {
-  getRaw(key: EnvKeyInput): string | undefined;
-  get(key: EnvKeyInput, def?: string): string | undefined;
-  isStrict(): boolean;
-}
 //#endregion
-export type { EnvKeyInput, EnvapterService };
+export type { EnvKeyInput };
 //# sourceMappingURL=Env.d.mts.map

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

@@ -1,5 +1,5 @@
+import { Environment } from "../core/Environment.mjs";
 import { EnvaptConverter } from "./Conversion.mjs";
-import { Environment } from "../core/EnvironmentMethods.mjs";
 
 //#region src/types/Options.d.ts
 /**
@@ -37,6 +37,13 @@ type ProfilesConfig = Partial<Record<Environment, EnvProfile>> & {
    */
   useDefaults?: boolean;
 };
+/**
+ * How the portable build's filesystem-only config APIs behave when called. `'warn'` (the default)
+ * warns once and no-ops, `'throw'` throws `FileApiUnsupported`. The node build runs these APIs
+ * normally and is unaffected by this value.
+ * @public
+ */
+type FileApiMode = 'warn' | 'throw';
 //#endregion
-export type { EnvProfile, EnvaptOptions, ProfilesConfig };
+export type { EnvProfile, EnvaptOptions, FileApiMode, ProfilesConfig };
 //# sourceMappingURL=Options.d.mts.map

package/dist/types/types/Schema.d.mts

@@ -2,23 +2,11 @@ import { StandardSchemaV1 } from "../infra/StandardSchema.mjs";
 
 //#region src/types/Schema.d.ts
 declare const _envaptErrBrand: unique symbol;
-/**
- * A branded string carrying a compile-time error message. The `unique symbol` brand cannot be
- * produced from user code, so the message string can't be copy-pasted to satisfy the type.
- */
 type Err<Msg extends string> = Msg & {
   readonly [_envaptErrBrand]: never;
 };
-/**
- * The {@link Err} returned when a Standard Schema's `validate` is async. envapt loads config at boot,
- * so async refinements are rejected at the type level.
- */
 type SchemaMustBeSync = Err<'Schema must be synchronous. envapt is boot-time config loading; async refinements (validate returning `Promise<Result>`) belong outside the env layer.'>;
-/**
- * Resolves to the schema when its `validate` is synchronous, or {@link SchemaMustBeSync} when it
- * returns a Promise.
- */
 type SchemaConstraint<Schema extends StandardSchemaV1> = ReturnType<Schema['~standard']['validate']> extends Promise<unknown> ? SchemaMustBeSync : Schema;
 //#endregion
-export type { Err, SchemaConstraint, SchemaMustBeSync };
+export type { SchemaConstraint };
 //# sourceMappingURL=Schema.d.mts.map

package/dist/types/types/Source.d.mts

@@ -1,49 +1,24 @@
 //#region src/types/Source.d.ts
-/**
- * A source with no filesystem: an injected object on the browser, or the Cloudflare `env` binding on
- * Workers. The `.env` cascade, profiles, and the `envPaths`/`baseDir`/`configureProfiles` APIs do not
- * apply. Only `readVars()` populates the cache.
- * @public
- */
-interface BareEnvSource {
-  /** Return every variable this source provides, as plain strings. */
+interface BareSource {
   readVars(): Record<string, string>;
-  /** Leave unset (or `false`) because a bare source has no filesystem. */
   readonly supportsFiles?: false;
 }
-/**
- * A filesystem-backed source, like the default {@link NodeEnvSource}. Setting `supportsFiles` to
- * `true` requires all four file capabilities, so the engine can load the `.env` cascade, resolve
- * `baseDir`, and mirror loaded keys back to the ambient environment.
- * @public
- */
-interface FileEnvSource {
-  /** Return every variable this source provides, as plain strings. */
+interface FileCapableSource {
   readVars(): Record<string, string>;
-  /** When `true`, the engine loads the `.env` cascade, profiles, and `envPaths` through the methods below. */
   readonly supportsFiles: true;
-  /** Read a file's text, or `undefined` when it is absent or unreadable. Backs the loader and existence checks. */
   readFile(path: string, encoding: string): string | undefined;
-  /** Join a relative `.env` path onto `baseDir`. Absolute paths are returned unchanged. */
   resolvePath(baseDir: string, candidate: string): string;
-  /** Normalize a `baseDir` value (a directory path, or a module / `file:` URL) to an absolute directory path. */
   normalizeBaseDir(value: string | URL): string;
-  /** Mirror loaded keys back to the ambient environment (e.g. `process.env`), backing `Envapter.syncProcessEnv`. */
   writeVars(vars: Record<string, string>): void;
 }
 /**
- * A pluggable source of environment variables. The default {@link NodeEnvSource} (a {@link FileEnvSource})
- * reads `process.env` plus the `.env` cascade. A {@link BareEnvSource} lets the same engine run where
- * there is no ambient environment (an injected object on the browser, the Cloudflare `env` binding on
- * Workers). Bind one with `Envapter.useSource`.
- * @public
- */
-type Source = BareEnvSource | FileEnvSource;
-/**
+ * A pluggable source of environment variables. The default {@link FileSource} reads `process.env` plus
+ * the `.env` cascade. A {@link PortableSource} lets the same engine run where there is no ambient
+ * environment (an injected object on the browser, the Cloudflare `env` binding on Workers). Bind one
+ * with `Envapter.useSource`.
  * @public
- * @deprecated Renamed to {@link Source} in v8.
  */
-type EnvSource = Source;
+type Source = BareSource | FileCapableSource;
 //#endregion
-export type { BareEnvSource, EnvSource, FileEnvSource, Source };
+export type { BareSource, FileCapableSource, Source };
 //# sourceMappingURL=Source.d.mts.map