envapt 7.1.0 → 8.0.0-next.1

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

package/dist/types/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 { Converters, CustomElementConverter } from "./converters/Converters.mjs";
+import { ConverterFunction, JsonValue, TimeFallback } from "./types/Conversion.mjs";
+import { StandardSchemaV1 } from "./infra/StandardSchema.mjs";
+import { EnvProfile, EnvaptOptions, FileApiMode, ProfilesConfig } from "./types/Options.mjs";
+import { Source } from "./types/Source.mjs";
 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, Converters, type CustomElementConverter, type DebugLevel, EnvBool, type EnvFileOptions, EnvNum, type EnvProfile, EnvStr, EnvTime, EnvUrl, Envapt, EnvaptError, EnvaptErrorCodes, type EnvaptOptions, NodeEnvapter as Envapter, Environment, type FileApiMode, FileSource, type JsonValue, PortableSource, type ProfilesConfig, type Source, type StandardSchemaV1, type TimeFallback, merge };

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

@@ -1,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 { Converters, CustomElementConverter } from "./converters/Converters.mjs";
+import { ConverterFunction, JsonValue, TimeFallback } from "./types/Conversion.mjs";
+import { StandardSchemaV1 } from "./infra/StandardSchema.mjs";
+import { EnvProfile, EnvaptOptions, FileApiMode, ProfilesConfig } from "./types/Options.mjs";
+import { Source } from "./types/Source.mjs";
 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, Converters, type CustomElementConverter, type DebugLevel, EnvBool, type EnvFileOptions, EnvNum, type EnvProfile, EnvStr, EnvTime, EnvUrl, Envapt, EnvaptError, EnvaptErrorCodes, type EnvaptOptions, PortableEnvapter as Envapter, Environment, type FileApiMode, type JsonValue, PortableSource, type ProfilesConfig, type Source, type StandardSchemaV1, type TimeFallback, merge };

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

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

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

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

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

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

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

@@ -9,6 +9,7 @@
  * `SchemaMustBeSync` brand in `Types.ts`) and at runtime by the Parser dispatch.
  *
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/standard-schema#any-conformant-validator-or-none}
  */
 interface StandardSchemaV1<Input = unknown, Output = Input> {
   /** The Standard Schema entry point holding the validator and the inferred input/output types. */
@@ -43,18 +44,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,14 @@
-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
+ * @see {@link https://envapt.materwelon.dev/docs/sources#the-providers}
  */
-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 +27,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
 /**
@@ -9,8 +9,9 @@ import { BareEnvSource } from "../types/Source.mjs";
  * still apply, which means they must be JSON-serializable. Without a filesystem the `.env` cascade and
  * file APIs do not apply.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/sources#the-providers}
  */
-declare class PortableSource implements 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,16 @@
+import { Source } from "../types/Source.mjs";
+
+//#region src/sources/merge.d.ts
+/**
+ * Compose several sources into one, read last-wins. A later member's `readVars()` value overrides an
+ * earlier member's for the same key. A member may be a `(key) => string | undefined` reader for a
+ * source that reads one key at a time, and it fills a key missing from every snapshot. Bind the result
+ * with `Envapter.useSource`. Throws {@link EnvaptErrorCodes.InvalidMergedSource} with no members or with
+ * more than one file-backed member.
+ * @public
+ * @see {@link https://envapt.materwelon.dev/docs/sources#combining-sources}
+ */
+declare function merge(...members: (Source | ((key: string) => string | undefined))[]): 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,35 +1,19 @@
 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
- * @public
- */
-type ConverterFunction<TFallback = unknown> = (raw: BaseInput, 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.
+ * 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
+ * @see {@link https://envapt.materwelon.dev/docs/converters#custom-converters}
  */
+type ConverterFunction<TFallback = unknown, TRaw extends BaseInput = BaseInput> = (raw: TRaw, fallback?: TFallback) => TFallback;
 type EnvaptConverter<TFallback> = PrimitiveConstructor | BuiltInConverter | ArrayOf | ConverterFunction<TFallback>;
 type JsonPrimitive = string | number | boolean | null;
 type JsonArray = JsonValue[];
@@ -39,6 +23,7 @@ interface JsonObject {
 /**
  * JSON value types for custom converters
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/converters#json}
  */
 type JsonValue = JsonPrimitive | JsonArray | JsonObject;
 interface ConverterMap {
@@ -55,26 +40,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
@@ -83,41 +49,16 @@ type TimeUnit = 'ms' | 's' | 'm' | 'h' | 'd' | 'w';
 /**
  * Fallback type for time duration conversions
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/converters#time-and-durations}
  */
 type TimeFallback = number | `${number}${TimeUnit}`;
-/**
- * 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,11 +1,12 @@
+import { Environment } from "../core/Environment.mjs";
 import { EnvaptConverter } from "./Conversion.mjs";
-import { Environment } from "../core/EnvironmentMethods.mjs";
 
 //#region src/types/Options.d.ts
 /**
  * Options for the \@Envapt decorator (modern API). `required: true` is mutually exclusive
  * with `fallback`; see the per-converter overloads in `Envapt.ts` for the type-level mutex.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/decorators#declaring-decorated-fields}
  */
 interface EnvaptOptions<TFallback = string> {
   /** Value returned when the variable is missing or empty. Mutually exclusive with `required: true`. */
@@ -18,6 +19,7 @@ interface EnvaptOptions<TFallback = string> {
 /**
  * Per-environment profile entry passed to `Envapter.configureProfiles`.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/environment#custom-profiles}
  */
 interface EnvProfile {
   /** One or more `.env` paths to load for this environment. Order matters: earlier paths take precedence. */
@@ -28,6 +30,7 @@ interface EnvProfile {
  * profile override. Unspecified environments fall through to the default cascade behavior
  * (`.env.${env}.local`, `.env.local`, `.env.${env}`, `.env`).
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/environment#custom-profiles}
  */
 type ProfilesConfig = Partial<Record<Environment, EnvProfile>> & {
   /**
@@ -37,6 +40,14 @@ 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
+ * @see {@link https://envapt.materwelon.dev/docs/compatibility#binding-by-runtime}
+ */
+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,27 @@
 //#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;
+  readVar?(key: string): string | undefined;
 }
-/**
- * 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;
+  readVar?(key: string): string | undefined;
 }
 /**
- * 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.
+ * @see {@link https://envapt.materwelon.dev/docs/sources#any-object-can-be-a-source}
  */
-type EnvSource = Source;
+type Source = BareSource | FileCapableSource;
 //#endregion
-export type { BareEnvSource, EnvSource, FileEnvSource, Source };
+export type { BareSource, FileCapableSource, Source };
 //# sourceMappingURL=Source.d.mts.map