envapt 7.0.3 → 8.0.0-next.0

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

@@ -1,19 +1,11 @@
 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 { EnvSource, FileEnvSource } 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: EnvSource;
   /**
    * Enable or disable strict mode. Default `false`. Setting refreshes the cache so
    * previously-cached converted values get re-evaluated under the new rule.
@@ -22,7 +14,7 @@ declare abstract class EnvapterBase {
   static get strict(): boolean;
   /**
    * 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
+   * bound source on first access. The setter overrides any env-var value. Output goes to stderr
    * on Node (the console elsewhere), prefixed with `[envapt]`.
    */
   static set debug(level: DebugLevel);
@@ -32,7 +24,7 @@ declare abstract class EnvapterBase {
    *
    * Only keys the loader actually wrote are mirrored, so collision behavior follows
    * `envFileOptions.override`: with the default `false`, pre-existing `process.env` values
-   * are preserved; with `true`, the file value wins in both the cache and the mirror.
+   * are preserved. With `true`, the file value wins in both the cache and the mirror.
    *
    * Flipping `false → true` mirrors the existing tracked delta immediately (no cache
    * refresh). Flipping `true → false` is one-way: previously mirrored keys remain in
@@ -40,19 +32,14 @@ declare abstract class EnvapterBase {
    */
   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: EnvSource): 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.
+   */
+  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}),
@@ -60,12 +47,11 @@ declare abstract class EnvapterBase {
    */
   static load(): void;
   /**
-   * Bind the environment {@link EnvSource}. On Node the entry binds {@link NodeEnvSource} for you
-   * (a `process.env` snapshot plus the `.env` cascade); on the browser or Workers, pass a
-   * `ManualEnvSource` / `WorkerEnvSource` (or any `EnvSource`) before reading. Clears and rebuilds
-   * the cache.
+   * 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.
    */
-  static useSource(source: EnvSource): void;
+  static useSource(source: Source): void;
   /**
    * Read an environment variable as its raw string, skipping parsing and conversion.
    */

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

@@ -0,0 +1,25 @@
+//#region src/core/Environment.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
+}
+//#endregion
+export { Environment };
+//# sourceMappingURL=Environment.d.mts.map

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,19 +1,16 @@
+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 { 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 { merge } from "./sources/merge.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 } from "./types/Source.mjs";
-import { EnvaptAccessorDecorator, EnvaptFieldDecorator } from "./types/Decorator.mjs";
-import { ManualEnvSource } from "./sources/ManualEnvSource.mjs";
-import { WorkerEnvSource } from "./sources/WorkerEnvSource.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, type PrimitiveConstructor, type ProfilesConfig, type SchemaConstraint, type SchemaMustBeSync, 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,18 +1,15 @@
+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 { 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 { merge } from "./sources/merge.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 } from "./types/Source.mjs";
-import { EnvaptAccessorDecorator, EnvaptFieldDecorator } from "./types/Decorator.mjs";
-import { ManualEnvSource } from "./sources/ManualEnvSource.mjs";
-import { WorkerEnvSource } from "./sources/WorkerEnvSource.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, type PrimitiveConstructor, type ProfilesConfig, type SchemaConstraint, type SchemaMustBeSync, 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

@@ -0,0 +1,24 @@
+import { BareSource } from "../types/Source.mjs";
+
+//#region src/sources/PortableSource.d.ts
+/**
+ * Environment source seeded from an object you provide, for every runtime without a filesystem. The
+ * config your bundler injects into a browser build (Vite's `import.meta.env`, a webpack `DefinePlugin`
+ * global), the Cloudflare `env` binding, a Vercel Edge or Fastly config object, a test fixture, or any
+ * plain object. Pass it straight through. Non-string values are JSON-stringified so the converters
+ * still apply, which means they must be JSON-serializable. Without a filesystem the `.env` cascade and
+ * file APIs do not apply.
+ * @public
+ */
+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;
+  /** Seed the source from `vars`. Non-string values are JSON-stringified so the converters still apply. */
+  constructor(vars: object);
+  /** Returns a snapshot clone of the provided object as plain strings. */
+  readVars(): Record<string, string>;
+}
+//#endregion
+export { PortableSource };
+//# sourceMappingURL=PortableSource.d.mts.map

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