envapt 4.1.1 → 5.0.1

package/dist/index.d.cts

@@ -1,86 +1,111 @@
-import { DotenvConfigOptions } from 'dotenv';
-
-/**
- * Enum for built-in converters
- * @public
- */
-declare enum Converters {
-    String = "string",
-    Number = "number",
-    Boolean = "boolean",
-    Bigint = "bigint",
-    Symbol = "symbol",
-    Integer = "integer",
-    Float = "float",
-    Json = "json",
-    Array = "array",
-    Url = "url",
-    Regexp = "regexp",
-    Date = "date",
-    Time = "time"
-}
+//#region src/converters/Converters.d.ts
+declare const SCALAR: {
+  readonly String: "string";
+  readonly Number: "number";
+  readonly Boolean: "boolean";
+  readonly Bigint: "bigint";
+  readonly Symbol: "symbol";
+  readonly Integer: "integer";
+  readonly Float: "float";
+  readonly Json: "json";
+  readonly Url: "url";
+  readonly Regexp: "regexp";
+  readonly Date: "date";
+  readonly Time: "time";
+};
 /**
- * Type alias for converter values to maintain compatibility with existing string-based API
- * @internal
+ * String tokens for every built-in scalar converter.
+ * @public
  */
-type ConverterValue = `${Converters}`;
+type ConverterToken = (typeof SCALAR)[keyof typeof SCALAR];
 /**
- * Valid array element converter types (excludes array, json, regexp)
- * @internal
+ * Custom element converter for use inside {@link Converters.array}. Receives the trimmed,
+ * non-empty raw string for one array slot and returns the parsed value.
+ * @public
  */
-type ArrayElementConverter = Exclude<Converters, Converters.Array | Converters.Json | Converters.Regexp>;
+type CustomElementConverter<TReturn = unknown> = (raw: string) => TReturn;
 /**
- * Type alias for array element converter values
- * @internal
+ * Valid element converters for {@link Converters.array}: any scalar token except
+ * `json` and `regexp` (those don't compose as array elements), or a custom function.
+ * @public
  */
-type ArrayElementConverterValue = `${ArrayElementConverter}`;
-
+type ArrayElement = Exclude<ConverterToken, 'json' | 'regexp'> | CustomElementConverter;
 /**
- * User defined options for dotenv configuration
- *
- * "processEnv" and "path" are managed by Envapter and should not be included in user-defined config.
+ * Phantom-branded token produced by {@link Converters.array}. The `T` type parameter carries
+ * the element converter through any variable indirection so inference survives. The
+ * `__envaptKind` discriminant is present at runtime for dispatch.
  * @public
  */
-type PermittedDotenvConfig = Omit<DotenvConfigOptions, 'processEnv' | 'path'>;
+interface ArrayOf<TElement extends ArrayElement = ArrayElement> {
+  readonly __envaptKind: 'array';
+  readonly of: TElement;
+  readonly delimiter: string;
+}
 /**
- * Built-in converter types for common environment variable patterns
- * @public
+ * Runtime type guard for tokens produced by {@link Converters.array}.
+ * @internal
  */
-type BuiltInConverter = ConverterValue | Converters;
+declare function isArrayOf(value: unknown): value is ArrayOf;
+type ArrayScalarElement = Exclude<ConverterToken, 'json' | 'regexp'>;
+declare function buildArrayConverter<TReturn>(opts: {
+  of: CustomElementConverter<TReturn>;
+  delimiter?: string;
+}): ArrayOf<CustomElementConverter<TReturn>>;
+declare function buildArrayConverter<TToken extends ArrayScalarElement>(opts: {
+  of: TToken;
+  delimiter?: string;
+}): ArrayOf<TToken>;
+declare function buildArrayConverter(opts?: {
+  delimiter?: string;
+}): ArrayOf<'string'>;
 /**
- * Primitive types supported by Envapter
+ * Built-in converters for environment variables. Use the scalar tokens (e.g. `Converters.Number`)
+ * for primitive types and the {@link Converters.array} builder for delimited lists.
+ *
+ * @example
+ * ```ts
+ * \@Envapt('PORT', { converter: Converters.Number, fallback: 3000 })
+ * static readonly port: number;
+ *
+ * \@Envapt('TAGS', { converter: Converters.array({ of: Converters.String, delimiter: ' ' }) })
+ * static readonly tags: string[];
+ * ```
+ *
  * @public
  */
-type PrimitiveConstructor = typeof String | typeof Number | typeof Boolean | typeof BigInt | typeof Symbol;
+declare const Converters: {
+  readonly array: typeof buildArrayConverter;
+  readonly String: "string";
+  readonly Number: "number";
+  readonly Boolean: "boolean";
+  readonly Bigint: "bigint";
+  readonly Symbol: "symbol";
+  readonly Integer: "integer";
+  readonly Float: "float";
+  readonly Json: "json";
+  readonly Url: "url";
+  readonly Regexp: "regexp";
+  readonly Date: "date";
+  readonly Time: "time";
+};
+//#endregion
+//#region src/types/Conversion.d.ts
 /**
- * Valid array converter element types (excludes array, json, regexp)
+ * Scalar built-in converter tokens (e.g. `'number'`, `'time'`).
+ * Excludes the array builder (see {@link ArrayOf}).
  * @public
  */
-type ValidArrayConverterBuiltInType = ArrayElementConverterValue | ArrayElementConverter;
+type BuiltInConverter = ConverterToken;
 /**
- * Array converter configuration for custom delimiters and element types
+ * Primitive types supported by Envapter
  * @public
  */
-interface ArrayConverter {
-    /**
-     * Delimiter to split the string by
-     */
-    delimiter: string;
-    /**
-     * Type to convert each array element to (excludes array, json, and regexp types)
-     */
-    type?: ArrayElementConverter | ArrayElementConverterValue;
-}
+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;
-/**
- * Accepted shape for environment variable lookups. Either a single key or an ordered list of keys.
- * @public
- */
-type EnvKeyInput = string | readonly [string, ...string[]];
 /**
  * Custom parser function type for environment variables
  * @param raw - Raw string value from environment
@@ -90,59 +115,40 @@ type EnvKeyInput = string | readonly [string, ...string[]];
  */
 type ConverterFunction<TFallback = unknown> = (raw: BaseInput, fallback?: TFallback) => TFallback;
 /**
- * Environment variable converter - can be a primitive constructor, built-in converter string, array converter object, or custom parser function
- * @see {@link PrimitiveConstructor} for primitive types
- * @see {@link Converters} for built-in types
- * @see {@link ArrayConverter} for array converter configuration
- * @see {@link ConverterFunction} for custom parser functions
+ * 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 | Converters | ConverterValue | ArrayConverter | ConverterFunction<TFallback>;
-/**
- * Options for the \@Envapt decorator (modern API)
- * @public
- */
-interface EnvaptOptions<TFallback = string> {
-    /**
-     * Default value to use if environment variable is not found
-     */
-    fallback?: TFallback;
-    /**
-     * Built-in converter, custom converter function, or boxed-primitives (String, Number, Boolean, Symbol, BigInt)
-     * @see {@link EnvaptConverter} for details
-     */
-    converter?: EnvaptConverter<TFallback>;
-}
+type EnvaptConverter<TFallback> = PrimitiveConstructor | BuiltInConverter | ArrayOf | ConverterFunction<TFallback>;
 type JsonPrimitive = string | number | boolean | null;
 type JsonArray = JsonValue[];
 interface JsonObject {
-    [key: string]: JsonValue;
+  [key: string]: JsonValue;
 }
 /**
  * JSON value types for custom converters
- * @internal
+ * @public
  */
 type JsonValue = JsonPrimitive | JsonArray | JsonObject;
 interface ConverterMap {
-    string: string;
-    number: number;
-    boolean: boolean;
-    bigint: bigint;
-    symbol: symbol;
-    integer: number;
-    float: number;
-    json: JsonValue;
-    array: string[];
-    url: URL;
-    regexp: RegExp;
-    date: Date;
-    time: number;
+  string: string;
+  number: number;
+  boolean: boolean;
+  bigint: bigint;
+  symbol: symbol;
+  integer: number;
+  float: number;
+  json: JsonValue;
+  url: URL;
+  regexp: RegExp;
+  date: Date;
+  time: number;
 }
 /**
- * Type mapping for built-in converters to their return types
+ * Type mapping for built-in scalar converters to their return types
  * @internal
  */
-type BuiltInConverterReturnType<ConverterKey extends BuiltInConverter> = ConverterKey extends Converters ? ConverterMap[`${ConverterKey}`] : ConverterKey extends keyof ConverterMap ? ConverterMap[ConverterKey] : never;
+type BuiltInConverterReturnType<ConverterKey extends BuiltInConverter> = ConverterMap[ConverterKey];
 /**
  * Return type for built-in converter functions
  * @internal
@@ -162,7 +168,12 @@ type MapOfConverterFunctions = Record<BuiltInConverter, BuiltInConverterFunction
  * Time unit types for duration conversions
  * @internal
  */
-type TimeUnit = 'ms' | 's' | 'm' | 'h';
+type TimeUnit = 'ms' | 's' | 'm' | 'h' | 'd' | 'w';
+/**
+ * Fallback type for time duration conversions
+ * @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.
@@ -170,16 +181,27 @@ type TimeUnit = 'ms' | 's' | 'm' | 'h';
  */
 type ConditionalReturn<ReturnType, TFallback> = TFallback extends undefined ? ReturnType | undefined : ReturnType;
 /**
- * Advanced type inference for built-in and array converters
- * Maps converter types to their expected return types
+ * 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 InferConverterReturnType<TConverter extends BuiltInConverter | ArrayConverter> = TConverter extends BuiltInConverter ? BuiltInConverterReturnType<TConverter> : TConverter extends ArrayConverter ? TConverter['type'] extends BuiltInConverter ? BuiltInConverterReturnType<TConverter['type']>[] : string[] : unknown[];
+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 extends BuiltInConverter | ArrayConverter, TFallback = undefined> = ConditionalReturn<InferConverterReturnType<TConverter>, TFallback>;
+type AdvancedConverterReturn<TConverter, TFallback = undefined> = ConditionalReturn<InferConverterReturnType<TConverter>, TFallback>;
 /**
  * Type inference for primitive constructor return types
  * @internal
@@ -190,17 +212,404 @@ type InferPrimitiveReturnType<TConstructor extends PrimitiveConstructor> = TCons
  * @internal
  */
 type InferPrimitiveFallbackType<TFallback extends string | number | boolean | bigint | symbol | undefined> = TFallback extends string ? string : TFallback extends number ? number : TFallback extends boolean ? boolean : TFallback extends bigint ? bigint : TFallback extends symbol ? symbol : undefined;
-
+//#endregion
+//#region src/StandardSchema.d.ts
+/**
+ * Standard Schema V1 interface. Inlined verbatim from the spec at https://standardschema.dev
+ * so envapt has zero runtime peer dependencies on any specific schema library
+ * (zod / valibot / arktype / etc).
+ *
+ * envapt narrows usage to SYNCHRONOUS schemas only: env loading is boot-time,
+ * `validate` returning `Promise<Result>` is rejected at the type level (see
+ * `SchemaMustBeSync` brand in `Types.ts`) and at runtime by the Parser dispatch.
+ *
+ * @public
+ */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+  interface Props<Input = unknown, Output = Input> {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+    readonly types?: Types<Input, Output> | undefined;
+  }
+  type Result<Output> = SuccessResult<Output> | FailureResult;
+  interface SuccessResult<Output> {
+    readonly value: Output;
+    readonly issues?: undefined;
+  }
+  interface FailureResult {
+    readonly issues: readonly Issue[];
+  }
+  interface Issue {
+    readonly message: string;
+    readonly path?: readonly (PropertyKey | PathSegment)[] | undefined;
+  }
+  interface PathSegment {
+    readonly key: PropertyKey;
+  }
+  interface Types<Input = unknown, Output = Input> {
+    readonly input: Input;
+    readonly output: Output;
+  }
+  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 `declare 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
+//#region src/types/Schema.d.ts
+declare const _envaptErrBrand: unique symbol;
+type Err<Msg extends string> = Msg & {
+  readonly [_envaptErrBrand]: never;
+};
+type SchemaMustBeSync = Err<'Schema must be synchronous. envapt is boot-time config loading; async refinements (validate returning `Promise<Result>`) belong outside the env layer.'>;
+type SchemaConstraint<Schema extends StandardSchemaV1> = ReturnType<Schema['~standard']['validate']> extends Promise<unknown> ? SchemaMustBeSync : Schema;
+//#endregion
+//#region src/Debug.d.ts
+/**
+ * Debug log levels for {@link Envapter.debug}. `silent` (default) emits nothing.
+ * `warn` covers signals that might indicate misconfiguration: failed file reads,
+ * unresolved templates (when not strict), fallback values used in place of missing
+ * env. `verbose` adds every loaded file, per-file key count, per-key load lines, and
+ * effective-paths / cache-rebuild notices.
+ * @public
+ */
+type DebugLevel = 'silent' | 'warn' | 'verbose';
+//#endregion
+//#region src/Dotenv.d.ts
+/**
+ * Public options for the internal `.env` loader. Mirrors the subset of dotenv's
+ * `config()` options that envapt actually supports (no DOTENV_KEY, no quiet).
+ * For debug output, use `Envapter.debug` (or the `ENVAPT_DEBUG` env var).
+ *
+ * @public
+ */
+interface EnvFileOptions {
+  /** Encoding for reading .env files. Defaults to 'utf8'. */
+  encoding?: BufferEncoding;
+  /** When true, later files override earlier ones (and existing processEnv values). Default false (first-wins). */
+  override?: boolean;
+}
+//#endregion
+//#region src/core/EnvapterBase.d.ts
+/**
+ * Base class for environment variable management
+ * Handles configuration, caching, and basic environment loading
+ * @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>;
+  /**
+   * Enable or disable strict mode. Default `false`. Setting refreshes the cache so
+   * previously-cached converted values get re-evaluated under the new rule.
+   */
+  static set strict(value: boolean);
+  static get strict(): boolean;
+  /**
+   * Set the debug log level. Defaults to `silent`. When unset, reads `ENVAPT_DEBUG` from
+   * `process.env` on first access; the setter overrides any env-var value. Output goes
+   * to stderr prefixed with `[envapt]`.
+   */
+  static set debug(level: DebugLevel);
+  static get debug(): DebugLevel;
+  /**
+   * Opt-in mirror of dotenv-loaded keys back to `process.env`. Default `false`.
+   *
+   * 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.
+   *
+   * Flipping `false → true` mirrors the existing tracked delta immediately (no cache
+   * refresh). Flipping `true → false` is one-way: previously mirrored keys remain in
+   * `process.env` until the process exits.
+   */
+  static set syncProcessEnv(value: boolean);
+  static get syncProcessEnv(): boolean;
+  protected static treatAsMissing(value: string | undefined): boolean;
+  /**
+   * Set custom .env file paths. Accepts either a single path or array of paths.
+   * Setting new paths clears the cache and reloads environment variables.
+   *
+   * When set, this takes absolute precedence. The dotenv-flow auto-cascade and any
+   * {@link configureProfiles} configuration are ignored.
+   */
+  static set envPaths(paths: string[] | string);
+  /**
+   * Get currently configured .env file paths
+   */
+  static get envPaths(): string[];
+  /**
+   * Set a base directory that relative `.env` paths resolve against instead of
+   * `process.cwd()`: the auto-cascade, {@link configureProfiles} paths, and relative
+   * `envPaths`. Absolute paths always bypass it. Pass a directory, or a module URL
+   * (`import.meta.url`, ESM) / `import.meta.dirname` / `__dirname` (CJS) to anchor
+   * resolution next to the calling file regardless of launch directory.
+   *
+   * Set this before `envPaths` so relative `envPaths` validate against the right directory.
+   * Unset (`undefined`) restores `process.cwd()` resolution.
+   */
+  static set baseDir(value: string | URL | undefined);
+  static get baseDir(): string | undefined;
+  private static normalizeBaseDir;
+  protected static resolveAgainstBase(candidate: string): string;
+  static set envFileOptions(config: EnvFileOptions);
+  /**
+   * Get current dotenv configuration options
+   */
+  static get envFileOptions(): EnvFileOptions;
+  protected static refreshCache(): void;
+  protected static mirrorToProcessEnv(): void;
+  /**
+   * Resolve the effective `.env` paths to load. Default implementation just returns the
+   * explicit `_envPaths` array; subclasses (`EnvironmentMethods`) override to layer in the
+   * dotenv-flow cascade and any {@link configureProfiles} overrides when `envPaths` was
+   * never explicitly set.
+   * @internal
+   */
+  protected static resolveEffectivePaths(): string[];
+  protected static resolveKeyInput(keyInput: EnvKeyInput): {
+    key: string;
+    value: string | undefined;
+  };
+  protected static get config(): Map<string, unknown>;
+  /**
+   * Eagerly load the `.env` cascade now instead of lazily on the first read. Idempotent: a no-op
+   * once the cache is built. Useful before mirroring to `process.env` (see {@link syncProcessEnv}),
+   * which is what the `envapt/config` side-effect entry does.
+   */
+  static load(): void;
+  /**
+   * Read an environment variable as its raw string, skipping parsing and conversion.
+   */
+  getRaw(key: EnvKeyInput): string | undefined;
+}
+//#endregion
+//#region src/core/EnvironmentMethods.d.ts
+/**
+ * Environment types supported by Envapter
+ * @public
+ */
+declare enum Environment {
+  Development = 0,
+  Staging = 1,
+  Production = 2
+}
+/**
+ * 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 getRawValue;
+  /**
+   * Get the current application environment
+   */
+  static get environment(): Environment;
+  /**
+   * Set the application environment. Accepts either Environment enum or string value.
+   */
+  static set environment(env: string | Environment);
+  /**
+   * @see {@link EnvironmentMethods.environment}
+   */
+  get environment(): Environment;
+  /**
+   * @see {@link EnvironmentMethods.environment}
+   */
+  set environment(env: string | Environment);
+  /**
+   * Check if the current environment is production
+   */
+  static get isProduction(): boolean;
+  /**
+   * @see {@link EnvironmentMethods.isProduction}
+   */
+  get isProduction(): boolean;
+  /**
+   * Check if the current environment is staging
+   */
+  static get isStaging(): boolean;
+  /**
+   * @see {@link EnvironmentMethods.isStaging}
+   */
+  get isStaging(): boolean;
+  /**
+   * Check if the current environment is development
+   */
+  static get isDevelopment(): boolean;
+  /**
+   * @see {@link EnvironmentMethods.isDevelopment}
+   */
+  get isDevelopment(): boolean;
+  protected static refreshCache(): void;
+  /**
+   * Configure per-environment `.env` path overrides on top of the dotenv-flow auto-cascade.
+   *
+   * When set, each `Environment` key's `paths` are loaded at higher precedence than the
+   * cascade for that environment. Unspecified environments still use the cascade as-is.
+   * Set `useDefaults: false` to disable the cascade entirely (load only the configured paths).
+   *
+   * Setting an explicit `Envapter.envPaths` value at any point overrides this configuration.
+   *
+   * @example
+   * ```ts
+   * Envapter.configureProfiles({
+   *   [Environment.Staging]: { paths: 'config/staging.env' },
+   *   [Environment.Production]: { paths: ['config/prod.env', 'secrets/prod.env'] }
+   * });
+   * ```
+   */
+  static configureProfiles(config: ProfilesConfig): void;
+  /**
+   * Reset all path-resolution configuration to defaults: clears any prior
+   * {@link configureProfiles} call AND any explicit `Envapter.envPaths` assignment.
+   * Returns the resolver to the pure dotenv-flow cascade.
+   */
+  static resetProfiles(): void;
+  /**
+   * Determine the current environment for cascade-file selection by reading `process.env`
+   * directly. Bypassing `this.config` to avoid a circular dependency (cascade selection
+   * happens before `.env` files are loaded). The post-load `Envapter.environment` value
+   * may differ if a loaded `.env` file declares its own `ENVIRONMENT`/`ENV`/`NODE_ENV`.
+   * @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
+   * {@link 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
+//#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
+ */
+interface EnvaptOptions<TFallback = string> {
+  fallback?: TFallback;
+  converter?: EnvaptConverter<TFallback>;
+  required?: boolean;
+}
+/**
+ * Per-environment profile entry passed to {@link configureProfiles}.
+ * @public
+ */
+interface EnvProfile {
+  /** One or more `.env` paths to load for this environment. Order matters: earlier paths take precedence. */
+  paths: string | string[];
+}
+/**
+ * Configuration object for {@link configureProfiles}. Maps each `Environment` to an optional
+ * profile override. Unspecified environments fall through to the default cascade behavior
+ * (`.env.${env}.local`, `.env.local`, `.env.${env}`, `.env`).
+ * @public
+ */
+type ProfilesConfig = Partial<Record<Environment, EnvProfile>> & {
+  /**
+   * When `false`, disables the default dotenv-flow cascade entirely. Only the explicitly
+   * configured paths are loaded. Defaults to `true` (cascade still runs, configured paths
+   * are layered on top with higher precedence).
+   */
+  useDefaults?: boolean;
+};
+//#endregion
+//#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
+//#region src/converters/ValueConverter.d.ts
 /**
- * Usage 1: Custom converter function with fallback provided
+ * Convert a resolved environment value to its declared type via built-in, primitive, array,
+ * custom, or Standard Schema converters.
+ * @internal
+ */
+declare class ValueConverter {
+  private readonly envService;
+  constructor(envService: EnvapterService);
+  convertValue<TFallback>(key: EnvKeyInput, fallback: TFallback | undefined, converter: EnvaptConverter<TFallback> | undefined, hasFallback: boolean): TFallback | null | undefined;
+  private processFallbackForConverter;
+  private convertPrimitiveToString;
+  private processBuiltInConverter;
+  private processArrayConverter;
+  private processCustomConverter;
+  private resolveConverter;
+  convertWithSchema(key: EnvKeyInput, schema: StandardSchemaV1, fallback: unknown, hasFallback: boolean): unknown;
+}
+//#endregion
+//#region src/decorators/Envapt.d.ts
+/**
+ * Usage 1: Either a custom converter function + fallback (both required), OR a fallback
+ * only (no converter).
  *
- * @param key - Environment variable name to load (string or ordered array of strings)
- * @param options - Configuration options with custom converter and required fallback
+ * @param key - Environment variable name(s) to load
+ * @param options - Configuration options
  * @public
  * @example
  * ```ts
- * // Custom converter that validates a non-empty API key
  * class Config extends Envapter {
+ *   // Custom converter that validates a non-empty API key
  *   \@Envapt('API_KEY', {
  *     fallback: 'default-key',
  *     converter(raw, _fallback) {
@@ -209,39 +618,66 @@ type InferPrimitiveFallbackType<TFallback extends string | number | boolean | bi
  *     }
  *   })
  *   static readonly apiKey: string;
+ *
+ *   // Fallback-only (no converter): string fallback
+ *   \@Envapt('LOG_FILE', { fallback: '/var/log/app.log' })
+ *   static readonly logFile: string;
+ *
+ *   // Fallback-only: arbitrary object fallback
+ *   \@Envapt('RETRY_POLICY', { fallback: { retries: 3, backoff: 'exponential' } })
+ *   static readonly retryPolicy: unknown;
  * }
  * ```
  */
 declare function Envapt<TFallback>(key: EnvKeyInput, options: {
-    converter: (raw: string | undefined, fallback: TFallback) => TFallback;
-    fallback: TFallback;
+  converter: (raw: string | undefined, fallback: TFallback) => TFallback;
+  fallback: TFallback;
+} | {
+  fallback: TFallback;
+  converter?: undefined;
 }): PropertyDecorator;
 /**
- * Usage 2: Custom converter function without fallback
+ * Usage 2: Custom converter function without fallback. Either omit `required` (returns the
+ * converter's output, possibly `undefined`) or pass `required: true` to throw `MissingEnvValue`
+ * on missing/empty values.
  *
  * @param key - Environment variable name(s) to load
- * @param options - Configuration options with custom converter only
+ * @param options - Configuration options with custom converter only, with optional `required: true`
  * @public
  * @example
  * ```ts
- * // Custom converter without providing a fallback
  * class Config extends Envapter {
  *   \@Envapt('FEATURE_FLAGS', { converter(raw) {
- *     // raw may be undefined — handle that here
  *     return raw ? raw.split('|').map(s => s.trim()) : [];
  *   } })
  *   static readonly featureFlags: string[];
+ *
+ *   \@Envapt('JWT_SECRET', {
+ *     converter: (raw) => Buffer.from(raw ?? '', 'base64'),
+ *     required: true
+ *   })
+ *   declare static readonly jwtSecret: Buffer;
  * }
  * ```
  */
 declare function Envapt<TReturnType>(key: EnvKeyInput, options: {
-    converter: ConverterFunction<TReturnType>;
+  converter: ConverterFunction<TReturnType>;
+  required?: false;
+} | {
+  converter: ConverterFunction<TReturnType>;
+  required: true;
 }): PropertyDecorator;
 /**
- * Usage 3: Built-in converter with optional fallback
+ * Usage 3: Built-in or array converter with optional fallback OR `required: true`.
+ *
+ * `InferConverterFallbackType` handles asymmetric cases: scalar `Converters.Time` accepts
+ * `TimeFallback`, and `ArrayOf<'time'>` accepts `TimeFallback[]`. Every other converter
+ * reduces to `InferConverterReturnType`. The two object-shape branches are mutually
+ * exclusive: either provide a `fallback`, or pass `required: true` to throw
+ * `MissingEnvValue` on missing/empty values.
  *
  * @param key - Environment variable name(s) to load
- * @param options - Configuration options with built-in converter
+ * @param options - Configuration options
  * @public
  * @example
  * ```ts
@@ -252,53 +688,40 @@ declare function Envapt<TReturnType>(key: EnvKeyInput, options: {
  *   \@Envapt('APP_PORT', { converter: Converters.Number, fallback: 3000 })
  *   static readonly port: number;
  *
- *   // Use Url converter with a string fallback (must match converter type)
- *   \@Envapt('APP_URL', { converter: Converters.Url, fallback: 'http://localhost:3000' })
+ *   // Url converter: the fallback is a URL instance, not a string
+ *   \@Envapt('APP_URL', { converter: Converters.Url, fallback: new URL('http://localhost:3000') })
  *   static readonly url: URL;
  *
  *   // Prefer CANARY_URL when present, otherwise fall back to APP_URL
  *   \@Envapt(['CANARY_URL', 'APP_URL'], { converter: Converters.Url })
  *   static readonly canaryUrl: URL | null;
- * }
- * ```
- */
-declare function Envapt<TConverter extends BuiltInConverter>(key: EnvKeyInput, options: {
-    converter: TConverter;
-    fallback?: InferConverterReturnType<TConverter> | undefined;
-}): PropertyDecorator;
-/**
- * Usage 4: Array converter with optional fallback
  *
- * @param key - Environment variable name(s) to load
- * @param options - Configuration options with array converter
- * @public
- * @example
- * ```ts
- * import { Converters } from 'envapt';
+ *   // `Converters.Time` accepts either a number (milliseconds) or a time-string fallback (`<integer><unit>`).
+ *   \@Envapt('REQUEST_TIMEOUT', { converter: Converters.Time, fallback: '10s' })
+ *   static readonly requestTimeout: number;
  *
- * class Config extends Envapter {
- *   // Comma-separated list of origins -> string[]
+ *   // Array converter: comma-separated list of origins -> string[]
  *   \@Envapt('ALLOWED_ORIGINS', {
- *     converter: { delimiter: ',', type: Converters.String },
+ *     converter: Converters.array({ of: Converters.String }),
  *     fallback: ['https://example.com']
  *   })
  *   static readonly allowedOrigins: string[];
  *
- *   // Pipe-separated ports -> number[]
- *   \@Envapt('PORTS', {
- *     converter: { delimiter: '|', type: Converters.Number },
- *     fallback: [3000]
- *   })
- *   static readonly ports: number[];
+ *   \@Envapt('DATABASE_URL', { converter: Converters.Url, required: true })
+ *   declare static readonly databaseUrl: URL;
  * }
  * ```
  */
-declare function Envapt<TConverter extends ArrayConverter>(key: EnvKeyInput, options: {
-    converter: TConverter;
-    fallback?: InferConverterReturnType<TConverter> | undefined;
+declare function Envapt<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, options: {
+  converter: TConverter;
+  fallback?: InferConverterFallbackType<TConverter> | undefined;
+  required?: false;
+} | {
+  converter: TConverter;
+  required: true;
 }): PropertyDecorator;
 /**
- * Usage 5: Primitive constructor with optional fallback
+ * Usage 4: Primitive constructor with optional fallback
  *
  * @param key - Environment variable name(s) to load
  * @param options - Configuration options with primitive constructor
@@ -316,35 +739,38 @@ declare function Envapt<TConverter extends ArrayConverter>(key: EnvKeyInput, opt
  * ```
  */
 declare function Envapt<TConstructor extends PrimitiveConstructor>(key: EnvKeyInput, options: {
-    converter: TConstructor;
-    fallback?: InferPrimitiveReturnType<TConstructor>;
+  converter: TConstructor;
+  fallback?: InferPrimitiveReturnType<TConstructor>;
+  required?: false;
+} | {
+  converter: TConstructor;
+  required: true;
 }): PropertyDecorator;
 /**
- * Usage 6: Fallback only (no converter)
+ * Usage 5: Required, no converter (raw string). Throws `MissingEnvValue` on first access if
+ * the env value is missing or empty (post-trim). Independent of global `Envapter.strict`.
+ * Combining `required: true` with `fallback` fails to match any overload at compile time;
+ * the runtime Validator catches dynamic objects that bypass the types.
  *
  * @param key - Environment variable name(s) to load
- * @param options - Configuration options with fallback only
+ * @param options - `{ required: true }`
  * @public
  * @example
  * ```ts
- * // Fallback-only usage (no converter)
  * class Config extends Envapter {
- *   \@Envapt('LOG_FILE', { fallback: '/var/log/app.log' })
- *   static readonly logFile: string;
- *
- *   \@Envapt('RETRY_POLICY', { fallback: { retries: 3, backoff: 'exponential' } })
- *   static readonly retryPolicy: unknown;
+ *   \@Envapt('API_KEY', { required: true })
+ *   declare static readonly apiKey: string;
  * }
  * ```
  */
-declare function Envapt<TFallback>(key: EnvKeyInput, options: {
-    fallback: TFallback;
-    converter?: undefined;
+declare function Envapt(key: EnvKeyInput, options: {
+  required: true;
 }): PropertyDecorator;
 /**
  * Classic API: No fallback
  *
  * @param key - Environment variable name(s) to load
+ * @public
  * @example
  * ```ts
  * // Classic API: no fallback — property will resolve from env or be null
@@ -362,6 +788,9 @@ declare function Envapt<_TReturnType = string | null>(key: EnvKeyInput): Propert
  * @param fallback - Default primitive value
  * @param converter - Optional primitive constructor (String, Number, etc.)
  * @public
+ * @deprecated - Use the options object: `@Envapt('KEY', { converter, fallback })`. The positional
+ * form only accepts primitive constructors and cannot express built-in tokens, array/custom
+ * converters, `schema`, or `required`. Deprecated in v5, removed in v6.
  * @example
  * ```ts
  * // Classic API with primitive fallback and optional primitive converter
@@ -377,227 +806,202 @@ declare function Envapt<_TReturnType = string | null>(key: EnvKeyInput): Propert
  * ```
  */
 declare function Envapt<TFallback extends string | number | boolean | bigint | symbol | undefined>(key: EnvKeyInput, fallback: InferPrimitiveFallbackType<TFallback>, converter?: PrimitiveConstructor): PropertyDecorator;
-
 /**
- * @internal
+ * Usage 6: Standard Schema v1 adapter (zod, valibot, arktype, hand-rolled). Synchronous
+ * schemas only; a Promise-returning `validate` triggers a runtime
+ * `InvalidUserDefinedConfig` throw. Combining `schema` with `converter` fails to match any
+ * overload at compile time; the runtime Validator catches dynamic objects that bypass the
+ * types.
+ * @public
  */
-interface EnvapterService {
-    getRaw(key: EnvKeyInput): string | undefined;
-    get(key: EnvKeyInput, def?: string): string | undefined;
-}
+declare function Envapt<Schema extends StandardSchemaV1>(key: EnvKeyInput, options: {
+  schema: SchemaConstraint<Schema>;
+  fallback?: InferSchemaOutput<Schema>;
+  required?: false;
+} | {
+  schema: SchemaConstraint<Schema>;
+  required: true;
+}): PropertyDecorator;
+//#endregion
+//#region src/decorators/SugarDecorators.d.ts
 /**
- * Parser class for handling environment variable template resolution and type conversion
- * @internal
+ * Shorthand for `@Envapt(key, { converter: Converters.Boolean, fallback })`.
+ * @public
  */
-declare class Parser {
-    private readonly envService;
-    private readonly TEMPLATE_REGEX;
-    constructor(envService: EnvapterService);
-    /**
-     * Resolve template variables in a string while handling circular references and missing variables
-     * @internal
-     */
-    resolveTemplate(key: string, value: string, stack?: Set<string>): string;
-    convertValue<TFallback>(key: EnvKeyInput, fallback: TFallback | undefined, converter: EnvaptConverter<TFallback> | undefined, hasFallback: boolean): TFallback | null | undefined;
-    private processFallbackForConverter;
-    private convertPrimitiveToString;
-    private processBuiltInConverter;
-    private processArrayConverter;
-    private processCustomConverter;
-    private resolveConverter;
-}
-
+declare function EnvBool(key: EnvKeyInput, fallback?: boolean): PropertyDecorator;
 /**
- * Base class for environment variable management
- * Handles configuration, caching, and basic environment loading
- * @internal
+ * Shorthand for `@Envapt(key, { converter: Converters.Number, fallback })`.
+ * @public
  */
-declare abstract class EnvapterBase {
-    protected static _envPaths: string[];
-    protected static _userDefinedDotenvConfig: PermittedDotenvConfig;
-    /**
-     * Set custom .env file paths. Accepts either a single path or array of paths.
-     * Setting new paths clears the cache and reloads environment variables.
-     */
-    static set envPaths(paths: string[] | string);
-    /**
-     * Get currently configured .env file paths
-     */
-    static get envPaths(): string[];
-    /**
-     * Set custom dotenv configuration options.
-     */
-    static set dotenvConfig(config: PermittedDotenvConfig);
-    /**
-     * Get current dotenv configuration options
-     */
-    static get dotenvConfig(): PermittedDotenvConfig;
-    protected static refreshCache(): void;
-    protected static resolveKeyInput(keyInput: EnvKeyInput): {
-        key: string;
-        value: string | undefined;
-    };
-    protected static get config(): Map<string, unknown>;
-    /**
-     * Get raw environment variable value without parsing or conversion.
-     */
-    getRaw(key: EnvKeyInput): string | undefined;
-}
-
+declare function EnvNum(key: EnvKeyInput, fallback?: number): PropertyDecorator;
 /**
- * Environment types supported by Envapter
+ * Shorthand for `@Envapt(key, { converter: Converters.String, fallback })`.
  * @public
  */
-declare enum Environment {
-    Development = 0,
-    Staging = 1,
-    Production = 2
-}
+declare function EnvStr(key: EnvKeyInput, fallback?: string): PropertyDecorator;
 /**
- * Mixin for environment detection and checking methods
+ * Shorthand for `@Envapt(key, { converter: Converters.Time, fallback })`. The fallback is a
+ * millisecond number or a time string (`'15m'`); the resolved value is always milliseconds.
+ * @public
+ */
+declare function EnvTime(key: EnvKeyInput, fallback?: TimeFallback): PropertyDecorator;
+/**
+ * Shorthand for `@Envapt(key, { converter: Converters.Url, fallback })`. The fallback is a `URL`
+ * instance, not a URL string.
+ * @public
+ */
+declare function EnvUrl(key: EnvKeyInput, fallback?: URL): PropertyDecorator;
+//#endregion
+//#region src/TemplateResolver.d.ts
+/**
+ * Resolve `${VAR}` template references in environment values, guarding against circular
+ * references and missing variables.
  * @internal
  */
-declare class EnvironmentMethods extends EnvapterBase {
-    protected static _environment: Environment | undefined;
-    protected static determineEnvironment(env?: string | Environment): void;
-    private static getRawValue;
-    /**
-     * Get the current application environment
-     */
-    static get environment(): Environment;
-    /**
-     * Set the application environment. Accepts either Environment enum or string value.
-     */
-    static set environment(env: string | Environment);
-    /**
-     * @see {@link EnvironmentMethods.environment}
-     */
-    get environment(): Environment;
-    /**
-     * @see {@link EnvironmentMethods.environment}
-     */
-    set environment(env: string | Environment);
-    /**
-     * Check if the current environment is production
-     */
-    static get isProduction(): boolean;
-    /**
-     * @see {@link EnvironmentMethods.isProduction}
-     */
-    get isProduction(): boolean;
-    /**
-     * Check if the current environment is staging
-     */
-    static get isStaging(): boolean;
-    /**
-     * @see {@link EnvironmentMethods.isStaging}
-     */
-    get isStaging(): boolean;
-    /**
-     * Check if the current environment is development
-     */
-    static get isDevelopment(): boolean;
-    /**
-     * @see {@link EnvironmentMethods.isDevelopment}
-     */
-    get isDevelopment(): boolean;
-    protected static refreshCache(): void;
+declare class TemplateResolver {
+  private readonly envService;
+  private readonly TEMPLATE_REGEX;
+  constructor(envService: EnvapterService);
+  resolveTemplate(key: string, value: string, stack?: Set<string>): string;
 }
-
+//#endregion
+//#region src/core/PrimitiveMethods.d.ts
 /**
- * Mixin for primitive environment variable getter methods
  * @internal
  */
 declare class PrimitiveMethods extends EnvironmentMethods implements EnvapterService {
-    protected static readonly parser: Parser;
-    private static _get;
-    /**
-     * Get a string environment variable with optional fallback.
-     * Supports template variable resolution using `${VAR}` syntax.
-     * Accepts a single key or an ordered array of keys (first match wins).
-     */
-    static get<Default extends string | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<string, Default>;
-    /**
-     * @see {@link PrimitiveMethods.get}
-     */
-    get(key: EnvKeyInput, def?: string): string | undefined;
-    /**
-     * Get a number environment variable with optional fallback.
-     * Automatically converts string values to numbers.
-     * Accepts a single key or an ordered array of keys (first match wins).
-     */
-    static getNumber<Default extends number | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<number, Default>;
-    /**
-     * @see {@link PrimitiveMethods.getNumber}
-     */
-    getNumber<Default extends number | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<number, Default>;
-    /**
-     * Get a boolean environment variable with optional fallback.
-     * Recognizes: `1`, `yes`, `true`, 'on' as **true**; `0`, `no`, `false`, 'off' as **false** (case-insensitive).
-     * Accepts a single key or an ordered array of keys (first match wins).
-     */
-    static getBoolean<Default extends boolean | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<boolean, Default>;
-    /**
-     * @see {@link PrimitiveMethods.getBoolean}
-     */
-    getBoolean<Default extends boolean | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<boolean, Default>;
-    /**
-     * Get a bigint environment variable with optional fallback.
-     * Automatically converts string values to bigint.
-     * Accepts a single key or an ordered array of keys (first match wins).
-     */
-    static getBigInt<Default extends bigint | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<bigint, Default>;
-    /**
-     * @see {@link PrimitiveMethods.getBigInt}
-     */
-    getBigInt<Default extends bigint | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<bigint, Default>;
-    /**
-     * Get a symbol environment variable with optional fallback.
-     * Creates a symbol from the string value.
-     * Accepts a single key or an ordered array of keys (first match wins).
-     */
-    static getSymbol<Default extends symbol | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<symbol, Default>;
-    /**
-     * @see {@link PrimitiveMethods.getSymbol}
-     */
-    getSymbol<Default extends symbol | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<symbol, Default>;
+  private static readonly service;
+  protected static readonly templateResolver: TemplateResolver;
+  protected static readonly valueConverter: ValueConverter;
+  isStrict(): boolean;
+  private static _get;
+  /**
+   * Get a string environment variable with optional fallback.
+   * Supports template variable resolution using `${VAR}` syntax.
+   * Accepts a single key or an ordered array of keys (first match wins).
+   */
+  static get<Default extends string | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<string, Default>;
+  /**
+   * @see {@link PrimitiveMethods.get}
+   */
+  get<Default extends string | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<string, Default>;
+  /**
+   * Get a number environment variable with optional fallback.
+   * Automatically converts string values to numbers.
+   * Accepts a single key or an ordered array of keys (first match wins).
+   */
+  static getNumber<Default extends number | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<number, Default>;
+  /**
+   * @see {@link PrimitiveMethods.getNumber}
+   */
+  getNumber<Default extends number | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<number, Default>;
+  /**
+   * Get a boolean environment variable with optional fallback.
+   * Recognizes: `1`, `yes`, `true`, `on` as **true**; `0`, `no`, `false`, `off` as **false** (case-insensitive).
+   * Accepts a single key or an ordered array of keys (first match wins).
+   */
+  static getBoolean<Default extends boolean | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<boolean, Default>;
+  /**
+   * @see {@link PrimitiveMethods.getBoolean}
+   */
+  getBoolean<Default extends boolean | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<boolean, Default>;
+  /**
+   * Get a bigint environment variable with optional fallback.
+   * Automatically converts string values to bigint.
+   * Accepts a single key or an ordered array of keys (first match wins).
+   */
+  static getBigInt<Default extends bigint | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<bigint, Default>;
+  /**
+   * @see {@link PrimitiveMethods.getBigInt}
+   */
+  getBigInt<Default extends bigint | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<bigint, Default>;
+  /**
+   * Get a symbol environment variable with optional fallback.
+   * Creates a symbol from the string value.
+   * Accepts a single key or an ordered array of keys (first match wins).
+   */
+  static getSymbol<Default extends symbol | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<symbol, Default>;
+  /**
+   * @see {@link PrimitiveMethods.getSymbol}
+   */
+  getSymbol<Default extends symbol | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<symbol, Default>;
+}
+//#endregion
+//#region src/core/AdvancedMethods.d.ts
+interface GetUsingRequiredOptions<TConverter> {
+  converter: TConverter;
+  required: true;
+}
+interface GetWithRequiredOptions<TReturnType> {
+  converter: ConverterFunction<TReturnType>;
+  required: true;
 }
-
 /**
  * Mixin for advanced methods for environment variable conversion using built-in and custom converters
  * @internal
  */
 declare class AdvancedMethods extends PrimitiveMethods {
-    /**
-     * Get an environment variable using a built-in converter.
-     * Supports both Converter enum values and array converter configurations.
-     * The key can be a single name or an ordered list; the first defined value wins.
-     */
-    static getUsing<TConverter extends BuiltInConverter | ArrayConverter, TFallback = undefined>(key: EnvKeyInput, converter: TConverter, fallback?: TFallback): AdvancedConverterReturn<TConverter, TFallback>;
-    static getUsing<TReturn>(key: EnvKeyInput, converter: BuiltInConverter | ArrayConverter, fallback?: TReturn): TReturn;
-    /**
-     * @see {@link AdvancedMethods.getUsing}
-     */
-    getUsing<TConverter extends BuiltInConverter | ArrayConverter, TFallback = undefined>(key: EnvKeyInput, converter: TConverter, fallback?: TFallback): AdvancedConverterReturn<TConverter, TFallback>;
-    getUsing<TReturn>(key: EnvKeyInput, converter: BuiltInConverter | ArrayConverter, fallback?: TReturn): TReturn;
-    /**
-     * Get an environment variable using a custom converter function.
-     * Accepts a single key or an ordered list for automatic fallback.
-     */
-    static getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(key: EnvKeyInput, converter: ConverterFunction<TReturnType>, fallback?: TFallback): ConditionalReturn<TReturnType, TFallback>;
-    /**
-     * @see {@link AdvancedMethods.getWith}
-     */
-    getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(key: EnvKeyInput, converter: ConverterFunction<TReturnType>, fallback?: TFallback): ConditionalReturn<TReturnType, TFallback>;
+  /**
+   * Get an environment variable using a built-in converter.
+   *
+   * Supports both scalar tokens (e.g. `Converters.Number`) and `ArrayOf<...>` tokens
+   * produced by `Converters.array(...)`. The key can be a single name or an ordered list;
+   * the first defined value wins.
+   */
+  static getUsing<TFallback extends TimeFallback | undefined = undefined>(key: EnvKeyInput, converter: 'time', fallback?: TFallback): ConditionalReturn<number, TFallback>;
+  static getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(key: EnvKeyInput, converter: TConverter, fallback?: TFallback): AdvancedConverterReturn<TConverter, TFallback>;
+  static getUsing<TReturn>(key: EnvKeyInput, converter: BuiltInConverter | ArrayOf, fallback?: TReturn): TReturn;
+  static getUsing(key: EnvKeyInput, options: GetUsingRequiredOptions<'time'>): number;
+  static getUsing<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, options: GetUsingRequiredOptions<TConverter>): InferConverterReturnType<TConverter>;
+  /**
+   * @see {@link AdvancedMethods.getUsing}
+   */
+  getUsing<TFallback extends TimeFallback | undefined = undefined>(key: EnvKeyInput, converter: 'time', fallback?: TFallback): ConditionalReturn<number, TFallback>;
+  getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(key: EnvKeyInput, converter: TConverter, fallback?: TFallback): AdvancedConverterReturn<TConverter, TFallback>;
+  getUsing<TReturn>(key: EnvKeyInput, converter: BuiltInConverter | ArrayOf, fallback?: TReturn): TReturn;
+  getUsing(key: EnvKeyInput, options: GetUsingRequiredOptions<'time'>): number;
+  getUsing<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, options: GetUsingRequiredOptions<TConverter>): InferConverterReturnType<TConverter>;
+  /**
+   * Get an environment variable using a custom converter function.
+   * Accepts a single key or an ordered list for automatic fallback.
+   */
+  static getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(key: EnvKeyInput, converter: ConverterFunction<TReturnType>, fallback?: TFallback): ConditionalReturn<TReturnType, TFallback>;
+  static getWith<TReturnType>(key: EnvKeyInput, options: GetWithRequiredOptions<TReturnType>): TReturnType;
+  /**
+   * @see {@link AdvancedMethods.getWith}
+   */
+  getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(key: EnvKeyInput, converter: ConverterFunction<TReturnType>, fallback?: TFallback): ConditionalReturn<TReturnType, TFallback>;
+  getWith<TReturnType>(key: EnvKeyInput, options: GetWithRequiredOptions<TReturnType>): TReturnType;
+  /**
+   * Validate an environment variable through a {@link StandardSchemaV1}-conformant schema
+   * (zod, valibot, arktype, etc). Throws `MissingEnvValue` if the env value is absent and
+   * no fallback is provided. The fallback, when provided, is returned as-is on missing;
+   * it does NOT pass through the schema (mirrors custom-converter behavior).
+   *
+   * Synchronous schemas only. A Promise-returning `validate` triggers an
+   * `InvalidUserDefinedConfig` throw at the call site.
+   *
+   * @example
+   * ```ts
+   * import { z } from 'zod';
+   * const port = Envapter.parse('PORT', z.coerce.number().min(1024).max(65535), 3000);
+   * ```
+   */
+  static parse<Schema extends StandardSchemaV1>(key: EnvKeyInput, schema: SchemaConstraint<Schema>, fallback?: InferSchemaOutput<Schema>): InferSchemaOutput<Schema>;
+  /**
+   * @see {@link AdvancedMethods.parse}
+   */
+  parse<Schema extends StandardSchemaV1>(key: EnvKeyInput, schema: SchemaConstraint<Schema>, fallback?: InferSchemaOutput<Schema>): InferSchemaOutput<Schema>;
 }
-
+//#endregion
+//#region src/Envapter.d.ts
 /**
  * Main configuration class for environment variable management.
  *
  * Provides both static and instance methods for retrieving typed environment variables
  * with support for template resolution, multiple .env files, and environment detection.
  *
- * Extend your own classes from this to define properties with \@Envapt decorators and provide access to environment variables methods.
+ * Extend your own classes from this to define properties with \@Envapt decorators and get access to environment-variable methods.
  *
  * @example
  * ```ts
@@ -615,67 +1019,109 @@ declare class AdvancedMethods extends PrimitiveMethods {
  * @public
  */
 declare class Envapter extends AdvancedMethods {
-    /**
-     * Tagged template literal for resolving environment variables in template strings.
-     *
-     * @example
-     * ```ts
-     * // Given API_HOST=api.example.com and API_PORT=8080 in environment
-     * const endpoint = Envapter.resolve`Connecting to ${'API_HOST'}:${'API_PORT'}`;
-     * // Returns: "Connecting to api.example.com:8080"
-     *
-     * // Works with template variables in .env too:
-     * // API_URL=https://${API_HOST}:${API_PORT}
-     * const message = Envapter.resolve`Service endpoint: ${'API_URL'}`;
-     * // Returns: "Service endpoint: https://api.example.com:8080"
-     * ```
-     */
-    static resolve(strings: TemplateStringsArray, ...keys: string[]): string;
-    /**
-     * @see {@link Envapter.resolve}
-     */
-    resolve(strings: TemplateStringsArray, ...keys: string[]): string;
+  /**
+   * Tagged template literal for resolving environment variables in template strings.
+   *
+   * @example
+   * ```ts
+   * // Given API_HOST=api.example.com and API_PORT=8080 in environment
+   * const endpoint = Envapter.resolve`Connecting to ${'API_HOST'}:${'API_PORT'}`;
+   * // Returns: "Connecting to api.example.com:8080"
+   *
+   * // Works with template variables in .env too:
+   * // API_URL=https://${API_HOST}:${API_PORT}
+   * const message = Envapter.resolve`Service endpoint: ${'API_URL'}`;
+   * // Returns: "Service endpoint: https://api.example.com:8080"
+   * ```
+   */
+  static resolve(strings: TemplateStringsArray, ...keys: string[]): string;
+  /**
+   * @see {@link Envapter.resolve}
+   */
+  resolve(strings: TemplateStringsArray, ...keys: string[]): string;
+  /**
+   * Assert that one or more environment variables are present and non-empty (post-trim,
+   * after template resolution). Throws `MissingEnvValue` listing every missing key.
+   *
+   * For typed fail-fast in functional code, use `Envapter.getUsing(key, { converter, required: true })`.
+   *
+   * @example
+   * ```ts
+   * Envapter.require('DATABASE_URL');
+   * Envapter.require('DATABASE_URL', 'API_KEY', 'SENTRY_DSN');
+   * ```
+   */
+  static require(...keys: [string, ...string[]]): void;
+  private static resolveAndValidate;
+  /**
+   * @see {@link Envapter.require}
+   */
+  require(...keys: [string, ...string[]]): void;
 }
-
+//#endregion
+//#region src/Error.d.ts
 declare enum EnvaptErrorCodes {
-    /** Thrown when an invalid fallback value is provided */
-    InvalidFallback = 101,
-    /** Thrown when fallback value type doesn't match expected converter type */
-    InvalidFallbackType = 102,
-    /** Thrown when array fallback contains elements of wrong type */
-    ArrayFallbackElementTypeMismatch = 103,
-    /** Thrown when fallback type doesn't match the specified converter */
-    FallbackConverterTypeMismatch = 104,
-    /** Thrown when invalid array converter configuration is provided */
-    InvalidArrayConverterType = 201,
-    /** Thrown when an invalid built-in converter is specified */
-    InvalidBuiltInConverter = 202,
-    /** Thrown when a custom converter is not a function */
-    InvalidCustomConverter = 203,
-    /** Thrown when converter type is not recognized */
-    InvalidConverterType = 204,
-    /** Thrown when primitive type coercion on fallback value fails */
-    PrimitiveCoercionFailed = 205,
-    /** Thrown when delimiter is missing in array converter configuration */
-    MissingDelimiter = 301,
-    /** Thrown when invalid user-defined configuration is provided */
-    InvalidUserDefinedConfig = 302,
-    /** Thrown when specified environment files don't exist */
-    EnvFilesNotFound = 303,
-    /** Thrown when no valid environment key is provided */
-    InvalidKeyInput = 304
+  /** Thrown when an invalid fallback value is provided */
+  InvalidFallback = 101,
+  /** Thrown when fallback value type doesn't match expected converter type */
+  InvalidFallbackType = 102,
+  /** Thrown when array fallback contains elements of wrong type */
+  ArrayFallbackElementTypeMismatch = 103,
+  /** Thrown when fallback type doesn't match the specified converter */
+  FallbackConverterTypeMismatch = 104,
+  /** Thrown when a time-string fallback is malformed (does not match the required `<integer><unit>` format) */
+  MalformedTimeFallback = 105,
+  /** Thrown when invalid array converter configuration is provided */
+  InvalidArrayConverterType = 201,
+  /** Thrown when an invalid built-in converter is specified */
+  InvalidBuiltInConverter = 202,
+  /** Thrown when a custom converter is not a function */
+  InvalidCustomConverter = 203,
+  /** Thrown when converter type is not recognized */
+  InvalidConverterType = 204,
+  /** Thrown when primitive type coercion on fallback value fails */
+  PrimitiveCoercionFailed = 205,
+  /** Thrown when an array element fails to convert to the configured element type */
+  ArrayElementConversionFailed = 206,
+  /** Thrown under strict mode when an array element is empty or whitespace only */
+  EmptyArrayElement = 207,
+  /** Thrown when a Standard Schema returns issues for a non-empty env value */
+  SchemaValidationFailed = 208,
+  /** Thrown when a Standard Schema's `validate` itself throws (e.g. a refinement that crashes) */
+  SchemaThrew = 209,
+  /** Thrown when delimiter is missing in array converter configuration */
+  MissingDelimiter = 301,
+  /** Thrown when invalid user-defined configuration is provided */
+  InvalidUserDefinedConfig = 302,
+  /** Thrown when specified environment files don't exist */
+  EnvFilesNotFound = 303,
+  /** Thrown when no valid environment key is provided */
+  InvalidKeyInput = 304,
+  /** Thrown when a required environment value is missing or empty (post-trim) */
+  MissingEnvValue = 305
+}
+interface EnvaptErrorOptions {
+  issues?: readonly StandardSchemaV1.Issue[];
+  cause?: unknown;
 }
 /**
  * Custom error for better DX and debugging when using Envapt.
  *
  * @example
  * ```ts
- * throw new EnvaptError(EnvaptErrorCode.InvalidFallback, "Invalid fallback value provided for environment variable.");
+ * throw new EnvaptError(EnvaptErrorCodes.InvalidFallback, "Invalid fallback value provided for environment variable.");
  * ```
  */
 declare class EnvaptError extends Error {
-    readonly code: EnvaptErrorCodes;
-    constructor(code: EnvaptErrorCodes, message: string);
+  readonly code: EnvaptErrorCodes;
+  /**
+   * Populated only for {@link EnvaptErrorCodes.SchemaValidationFailed} (208). For every other
+   * code this is `undefined`. Lets callers do `if (err.code === 208) err.issues?.forEach(...)`
+   * without a type cast.
+   */
+  readonly issues: readonly StandardSchemaV1.Issue[] | undefined;
+  constructor(code: EnvaptErrorCodes, message: string, options?: EnvaptErrorOptions);
 }
-
-export { type AdvancedConverterReturn, type ArrayConverter, type BuiltInConverter, type BuiltInConverterFunction, type ConditionalReturn, type ConverterFunction, Converters, type EnvKeyInput, Envapt, type EnvaptConverter, EnvaptError, EnvaptErrorCodes, type EnvaptOptions, Envapter, Environment, type InferConverterReturnType, type InferPrimitiveFallbackType, type InferPrimitiveReturnType, type JsonValue, type MapOfConverterFunctions, type PermittedDotenvConfig, type PrimitiveConstructor, type TimeUnit, type ValidArrayConverterBuiltInType };
+//#endregion
+export { type AdvancedConverterReturn, type ArrayElement, type ArrayOf, type BuiltInConverter, type BuiltInConverterFunction, type ConditionalReturn, type ConverterFunction, type ConverterToken, Converters, type CustomElementConverter, type DebugLevel, EnvBool, type EnvFileOptions, type EnvKeyInput, EnvNum, type EnvProfile, EnvStr, EnvTime, EnvUrl, Envapt, type EnvaptConverter, EnvaptError, EnvaptErrorCodes, type EnvaptOptions, Envapter, Environment, type Err, type InferConverterFallbackType, type InferConverterReturnType, type InferPrimitiveFallbackType, type InferPrimitiveReturnType, type InferSchemaInput, type InferSchemaOutput, type JsonValue, type MapOfConverterFunctions, type PrimitiveConstructor, type ProfilesConfig, type SchemaConstraint, type SchemaMustBeSync, type StandardSchemaV1, type TimeFallback, type TimeUnit, isArrayOf };
+//# sourceMappingURL=index.d.cts.map