envapt 8.0.0-next.0 → 8.0.0-next.1

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

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

package/dist/types/index.d.mts

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -2,6 +2,7 @@
 interface BareSource {
   readVars(): Record<string, string>;
   readonly supportsFiles?: false;
+  readVar?(key: string): string | undefined;
 }
 interface FileCapableSource {
   readVars(): Record<string, string>;
@@ -10,6 +11,7 @@ interface FileCapableSource {
   resolvePath(baseDir: string, candidate: string): string;
   normalizeBaseDir(value: string | URL): string;
   writeVars(vars: Record<string, string>): void;
+  readVar?(key: string): string | undefined;
 }
 /**
  * A pluggable source of environment variables. The default {@link FileSource} reads `process.env` plus
@@ -17,6 +19,7 @@ interface FileCapableSource {
  * environment (an injected object on the browser, the Cloudflare `env` binding on Workers). Bind one
  * with `Envapter.useSource`.
  * @public
+ * @see {@link https://envapt.materwelon.dev/docs/sources#any-object-can-be-a-source}
  */
 type Source = BareSource | FileCapableSource;
 //#endregion

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "envapt",
   "type": "module",
-  "version": "8.0.0-next.0",
+  "version": "8.0.0-next.1",
   "description": "Type-safe config for TypeScript. Read typed values from any source, process.env, .env files, Cloudflare Workers bindings, browser bundles, or any object you supply. Zero runtime dependencies, one API across Node, Bun, Deno, Workers, and the browser. TC39 accessor decorators (legacy decorators at envapt/legacy), converters, and Standard Schema (zod/valibot/arktype) validation.",
   "types": "./dist/types/index.d.mts",
   "exports": {