ultraenv 1.0.0

package/dist/schema/index.d.cts

@@ -0,0 +1,1244 @@
+/** Discriminated union parse result — success or failure */
+type ParseResult<T> = {
+    readonly success: true;
+    readonly value: T;
+} | {
+    readonly success: false;
+    readonly error: string;
+};
+/** Configuration for conditional schema application */
+interface ConditionalConfig {
+    /** Function that checks whether this schema should apply */
+    check: (env: Record<string, unknown>) => boolean;
+}
+/** Metadata attached to every schema builder */
+interface SchemaMetadata {
+    /** Human-readable description for documentation */
+    description?: string;
+    /** Example value for documentation */
+    example?: string;
+    /** Whether this value is a secret (should be masked in logs) */
+    isSecret: boolean;
+    /** Whether this value is deprecated */
+    isDeprecated: boolean;
+    /** Deprecation message */
+    deprecationMessage?: string;
+    /** Alternative variable names that should map to this schema */
+    aliases: readonly string[];
+    /** Whether the field is required */
+    required: boolean;
+    /** Whether a default value has been set */
+    hasDefault: boolean;
+    /** The raw default value (before parsing) */
+    rawDefaultValue?: string;
+    /** Runtime type name for error messages */
+    typeName: string;
+    /** Conditional configuration */
+    conditional?: ConditionalConfig;
+}
+/** Prevent TypeScript from inferring a more specific type */
+type NoInfer<T> = T extends infer U ? U : never;
+/** Extract the output type from a SchemaBuilder */
+type ExtractType$1<S> = S extends SchemaBuilder<infer T> ? T : never;
+/** Check if a schema is optional */
+type IsOptional<S> = S extends {
+    __optional: true;
+} ? true : false;
+/** Extract the default value type from a schema */
+type ExtractDefault<S> = S extends {
+    __default: infer D;
+} ? D : never;
+/** Resolve the final output type of a schema */
+type ResolveOutput$1<S> = S extends {
+    __optional: true;
+} ? ExtractType$1<S> | undefined : S extends {
+    __default: infer D;
+} ? D : ExtractType$1<S>;
+/**
+ * Core chainable schema builder with full TypeScript type inference.
+ *
+ * @typeParam TOutput - The output type after parsing and validation
+ *
+ * @example
+ * ```typescript
+ * const portSchema = t.number().port().default(3000);
+ * // portSchema._parse("8080") → { success: true, value: 8080 }
+ * // portSchema._parse("abc")  → { success: false, error: "..." }
+ * ```
+ */
+declare class SchemaBuilder<TOutput> {
+    /** Internal parser function: string → ParseResult<TOutput> */
+    protected _parser: (raw: string) => ParseResult<TOutput>;
+    /** Ordered list of validator functions: value → error message or null */
+    protected _validators: ReadonlyArray<(value: TOutput) => string | null>;
+    /** Ordered list of transform functions applied after validation */
+    protected _transforms: ReadonlyArray<(value: TOutput) => TOutput>;
+    /** Schema metadata */
+    protected _meta: SchemaMetadata;
+    constructor(parser: (raw: string) => ParseResult<TOutput>, typeName: string);
+    /**
+     * Parse a raw string value into the output type.
+     * Runs the parser, then all validators and transforms.
+     */
+    _parse(raw: string): ParseResult<TOutput>;
+    /**
+     * Validate an already-parsed value against all registered validators.
+     * Returns an error message string, or null if validation passes.
+     */
+    _validate(value: TOutput): string | null;
+    /** Get a readonly view of the schema metadata */
+    get meta(): Readonly<SchemaMetadata>;
+    /** Whether this schema is effectively optional (marked optional or has default) */
+    get isOptional(): boolean;
+    /** The runtime type name string */
+    get typeName(): string;
+    /** Get the default value, parsing it if a raw default exists */
+    getDefaultValue(): TOutput | undefined;
+    /** Return a composed reference to this builder for chaining */
+    get chain(): SchemaBuilder<TOutput>;
+    /** Add a human-readable description */
+    description(desc: string): this;
+    /** Set an example value for documentation */
+    example(ex: NoInfer<TOutput>): this;
+    /**
+     * Mark this field as optional. The output type becomes `TOutput | undefined`.
+     */
+    optional(): this & {
+        __optional: true;
+    };
+    /**
+     * Mark this field as required.
+     */
+    required(): this;
+    /**
+     * Set a default value. The field becomes effectively optional.
+     * The output type remains `TOutput` (guaranteed by the default).
+     */
+    default(value: NoInfer<TOutput>): this & {
+        __default: NoInfer<TOutput>;
+    };
+    /** Mark this field as a secret (masks in logs) */
+    secret(): this;
+    /** Mark this field as deprecated with a message */
+    deprecated(message: string): this;
+    /** Add alternative variable names */
+    alias(...names: string[]): this;
+    /** Add a transform function applied after validation */
+    transform(fn: (value: TOutput) => TOutput): this;
+    /** Add a custom validation function */
+    custom(fn: (value: TOutput) => string | null): this;
+    /**
+     * Apply this schema only when a condition is met.
+     * The condition receives the current env values.
+     */
+    when(check: (env: Record<string, unknown>) => boolean): this;
+    /** Add a validator function (used by type-specific subclasses) */
+    protected _addValidator(validator: (value: TOutput) => string | null): void;
+    /** Add a transform function (used by type-specific subclasses) */
+    protected _addTransform(fn: (value: TOutput) => TOutput): void;
+    /** Replace the parser function (used for type narrowing) */
+    protected _setParser(parser: (raw: string) => ParseResult<TOutput>): void;
+    /** Apply all transforms to a value */
+    protected _applyTransforms(value: TOutput): TOutput;
+    /** Clone this builder (for composition) */
+    clone(): SchemaBuilder<TOutput>;
+}
+
+/** A schema definition mapping variable names to schema builders */
+type SchemaDefinition = Record<string, SchemaBuilder<unknown>>;
+/** Error entry from validation */
+interface ValidationErrorEntry {
+    /** The variable name */
+    field: string;
+    /** The raw string value (or empty string if missing) */
+    rawValue: string;
+    /** Human-readable error message */
+    message: string;
+    /** The expected type */
+    expected: string;
+    /** Schema metadata for context */
+    meta: Readonly<SchemaMetadata>;
+}
+/** Warning entry from validation (non-blocking) */
+interface ValidationWarningEntry {
+    /** The variable name */
+    field: string;
+    /** The raw string value */
+    rawValue: string;
+    /** Warning message */
+    message: string;
+    /** Warning code */
+    code: string;
+}
+/** Final result of validation */
+interface EngineValidationResult {
+    /** Whether all validations passed (no errors) */
+    valid: boolean;
+    /** All validation errors (blocking) */
+    errors: readonly ValidationErrorEntry[];
+    /** All warnings (non-blocking) */
+    warnings: readonly ValidationWarningEntry[];
+    /** Successfully validated values */
+    values: Record<string, unknown>;
+    /** Unknown variables not in schema (only when strict mode) */
+    unknown: readonly string[];
+}
+/** Options for the validation engine */
+interface EngineOptions {
+    /** Whether to fail on unknown variables not in the schema — default: false */
+    strict?: boolean;
+    /** Whether to stop on first error — default: false */
+    abortEarly?: boolean;
+    /** Whether to include deprecation warnings — default: true */
+    deprecationWarnings?: boolean;
+}
+/**
+ * Validate environment variables against a schema definition.
+ *
+ * @param vars - The raw environment variable key-value pairs
+ * @param schema - The schema definition mapping names to builders
+ * @param options - Validation options
+ * @returns The complete validation result
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   PORT: t.number().port().default(3000),
+ *   HOST: t.string().hostname().default('localhost'),
+ *   DEBUG: t.boolean().optional(),
+ * };
+ *
+ * const result = validate(process.env, schema);
+ * if (result.valid) {
+ *   console.log(result.values.PORT); // 3000 (number)
+ * }
+ * ```
+ */
+declare function validate(vars: Record<string, string>, schema: SchemaDefinition, options?: EngineOptions): EngineValidationResult;
+/**
+ * Validate a single value against a schema builder.
+ * Useful for testing individual validators.
+ */
+declare function validateValue<T>(rawValue: string | undefined, builder: SchemaBuilder<T>): ParseResult<T>;
+/**
+ * Create a validation summary string for human-readable output.
+ */
+declare function formatValidationResult(result: EngineValidationResult): string;
+
+/**
+ * Extract the output type from a SchemaBuilder instance.
+ *
+ * @example
+ * ```typescript
+ * type T = ExtractType<typeof t.number().port()>;
+ * // T = number
+ *
+ * type T2 = ExtractType<typeof t.enum(['a', 'b'] as const)>;
+ * // T2 = 'a' | 'b'
+ * ```
+ */
+type ExtractType<S> = S extends SchemaBuilder<infer T> ? T : never;
+/**
+ * Resolve the final output type of a schema, considering optional and default.
+ *
+ * - If optional: T | undefined
+ * - If has default: D (the default type)
+ * - Otherwise: T
+ *
+ * @example
+ * ```typescript
+ * type V1 = ResolveOutput<typeof t.string()>;
+ * // V1 = string
+ *
+ * type V2 = ResolveOutput<typeof t.string().optional()>;
+ * // V2 = string | undefined
+ *
+ * type V3 = ResolveOutput<typeof t.number().default(3000)>;
+ * // V3 = number
+ * ```
+ */
+type ResolveOutput<S> = S extends {
+    __optional: true;
+} ? ExtractType<S> | undefined : S extends {
+    __default: infer D;
+} ? D : ExtractType<S>;
+/**
+ * Infer a complete typed object from a schema definition.
+ * This is the main type used by `defineEnv` for its return type.
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   PORT: t.number().port().default(3000),
+ *   HOST: t.string().hostname(),
+ *   NODE_ENV: t.enum(['dev', 'prod'] as const),
+ *   DEBUG: t.boolean().optional(),
+ * };
+ *
+ * type Env = InferSchema<typeof schema>;
+ * // Env = {
+ * //   PORT: number;       // has default, so number (not undefined)
+ * //   HOST: string;       // required
+ * //   NODE_ENV: 'dev' | 'prod';  // enum narrows the type
+ * //   DEBUG: boolean | undefined; // optional
+ * // }
+ * ```
+ */
+type InferSchema<T extends Record<string, SchemaBuilder<unknown>>> = {
+    readonly [K in keyof T]: ResolveOutput<T[K]>;
+};
+/**
+ * Make all fields of an inferred schema required (remove undefined).
+ * Useful when you know all defaults are applied.
+ */
+type RequiredSchema<T> = {
+    readonly [K in keyof T]: Exclude<T[K], undefined>;
+};
+/**
+ * Make all fields of an inferred schema optional (add undefined).
+ * Useful for partial configs.
+ */
+type PartialSchema<T> = {
+    readonly [K in keyof T]: T[K] | undefined;
+};
+/**
+ * Extract only the required fields from a schema.
+ */
+type RequiredFields<T extends Record<string, unknown>> = {
+    readonly [K in keyof T as undefined extends T[K] ? never : K]: T[K];
+};
+/**
+ * Extract only the optional fields from a schema.
+ */
+type OptionalFields<T extends Record<string, unknown>> = {
+    readonly [K in keyof T as undefined extends T[K] ? K : never]: T[K];
+};
+/**
+ * Omit fields from a schema definition (preserves types).
+ */
+type SchemaOmit<T extends Record<string, SchemaBuilder<unknown>>, K extends keyof T> = Omit<T, K>;
+/**
+ * Pick fields from a schema definition (preserves types).
+ */
+type SchemaPick<T extends Record<string, SchemaBuilder<unknown>>, K extends keyof T> = Pick<T, K>;
+/**
+ * Merge two schema definitions.
+ * Values from B override values from A for overlapping keys.
+ */
+type SchemaMerge<A extends Record<string, SchemaBuilder<unknown>>, B extends Record<string, SchemaBuilder<unknown>>> = Omit<A, keyof B> & B;
+/**
+ * Get the union of all output types in a schema.
+ */
+type SchemaValueUnion<T extends Record<string, SchemaBuilder<unknown>>> = ExtractType<T[keyof T]>;
+/**
+ * Create a mapped type that wraps each value in a Promise.
+ */
+type AsyncSchema<T extends Record<string, SchemaBuilder<unknown>>> = {
+    readonly [K in keyof T]: Promise<ResolveOutput<T[K]>>;
+};
+
+interface UrlOptions {
+    /** Allowed protocols (default: ['http', 'https']) */
+    protocols?: readonly string[];
+}
+interface UuidOptions {
+    /** Specific UUID version to validate (1-7). If omitted, accepts any version. */
+    version?: 1 | 2 | 3 | 4 | 5 | 6 | 7;
+}
+/**
+ * Chainable string schema builder with all string-specific validators.
+ *
+ * @typeParam T - The string literal union type (defaults to string)
+ *
+ * @example
+ * ```typescript
+ * const email = t.string().email();
+ * const role = t.string().oneOf(['admin', 'user'] as const); // type: 'admin' | 'user'
+ * const host = t.string().url({ protocols: ['https'] });
+ * ```
+ */
+declare class StringSchemaBuilder<T extends string = string> extends SchemaBuilder<T> {
+    constructor();
+    /** Validate as an email address */
+    email(): StringSchemaBuilder<T>;
+    /** Validate as a URL with optional protocol restriction */
+    url(opts?: UrlOptions): StringSchemaBuilder<T>;
+    /** Validate as a UUID (optionally restrict to a specific version 1-7) */
+    uuid(version?: 1 | 2 | 3 | 4 | 5 | 6 | 7): StringSchemaBuilder<T>;
+    /** Validate as a hex string (with optional 0x prefix) */
+    hex(): StringSchemaBuilder<T>;
+    /** Validate as a base64-encoded string */
+    base64(): StringSchemaBuilder<T>;
+    /** Validate that the string contains only letters and numbers */
+    alphanumeric(): StringSchemaBuilder<T>;
+    /** Convert to lowercase */
+    lowercase(): StringSchemaBuilder<T>;
+    /** Convert to uppercase */
+    uppercase(): StringSchemaBuilder<T>;
+    /** Trim whitespace from both ends */
+    trim(): StringSchemaBuilder<T>;
+    /** Minimum string length */
+    minLength(n: number): StringSchemaBuilder<T>;
+    /** Maximum string length */
+    maxLength(n: number): StringSchemaBuilder<T>;
+    /** Exact string length */
+    length(n: number): StringSchemaBuilder<T>;
+    /** Match a regular expression pattern */
+    pattern(regex: RegExp): StringSchemaBuilder<T>;
+    /** Must start with a specific prefix */
+    startsWith(prefix: string): StringSchemaBuilder<T>;
+    /** Must end with a specific suffix */
+    endsWith(suffix: string): StringSchemaBuilder<T>;
+    /** Must contain a specific substring */
+    includes(substring: string): StringSchemaBuilder<T>;
+    /** Restrict to one of the specified values (alias for enum) */
+    oneOf<L extends string>(values: readonly L[]): StringSchemaBuilder<L>;
+    /** Restrict to an enum of literal values — narrows the output type */
+    enum<L extends string>(values: readonly L[]): StringSchemaBuilder<L>;
+    /** Non-empty string */
+    nonempty(): StringSchemaBuilder<T>;
+    /** Must match a valid JSON string (checks parseability) */
+    json(): StringSchemaBuilder<T>;
+}
+/** Create a new string schema builder */
+declare function createStringSchema<T extends string = string>(): StringSchemaBuilder<T>;
+
+/**
+ * Chainable number schema builder with all number-specific validators.
+ *
+ * @typeParam T - The number literal type (defaults to number)
+ *
+ * @example
+ * ```typescript
+ * const port = t.number().port().default(3000);
+ * const pct = t.number().percentage().min(0).max(100);
+ * ```
+ */
+declare class NumberSchemaBuilder<T extends number = number> extends SchemaBuilder<T> {
+    constructor();
+    /** Must be an integer (no decimals) */
+    integer(): NumberSchemaBuilder<T>;
+    /** Must be a float (semantic marker — all JS numbers are doubles) */
+    float(): NumberSchemaBuilder<T>;
+    /** Minimum value (inclusive) */
+    min(n: number): NumberSchemaBuilder<T>;
+    /** Maximum value (inclusive) */
+    max(n: number): NumberSchemaBuilder<T>;
+    /** Must be positive (> 0) */
+    positive(): NumberSchemaBuilder<T>;
+    /** Must be negative (< 0) */
+    negative(): NumberSchemaBuilder<T>;
+    /** Must be non-negative (>= 0) */
+    nonNegative(): NumberSchemaBuilder<T>;
+    /** Must be a valid network port (1-65535) */
+    port(): NumberSchemaBuilder<T>;
+    /** Must be a percentage (0-100) */
+    percentage(): NumberSchemaBuilder<T>;
+    /** Must be finite (no Infinity or NaN) */
+    finite(): NumberSchemaBuilder<T>;
+    /** Must be one of the specified values — narrows the output type */
+    oneOf<const L extends number>(values: readonly L[]): NumberSchemaBuilder<L>;
+    /** Must be a multiple of the given number */
+    step(n: number): NumberSchemaBuilder<T>;
+    /** Must be a safe integer (-(2^53 - 1) to 2^53 - 1) */
+    safeInt(): NumberSchemaBuilder<T>;
+}
+/** Create a new number schema builder */
+declare function createNumberSchema<T extends number = number>(): NumberSchemaBuilder<T>;
+
+/**
+ * Chainable boolean schema builder.
+ *
+ * @example
+ * ```typescript
+ * const debug = t.boolean().default(false);
+ * // debug._parse("true") → { success: true, value: true }
+ * // debug._parse("1")    → { success: true, value: true }
+ * // debug._parse("no")   → { success: true, value: false }
+ * // debug._parse("abc")  → { success: false, error: "..." }
+ * ```
+ */
+declare class BooleanSchemaBuilder extends SchemaBuilder<boolean> {
+    private _truthyValues;
+    private _falsyValues;
+    constructor();
+    /**
+     * Override the set of truthy values (case-insensitive).
+     * Common defaults: true, 1, yes, on
+     */
+    truthy(values: readonly string[]): BooleanSchemaBuilder;
+    /**
+     * Override the set of falsy values (case-insensitive).
+     * Common defaults: false, 0, no, off, ''
+     */
+    falsy(values: readonly string[]): BooleanSchemaBuilder;
+    /** Rebuild the parser function with current truthy/falsy sets */
+    private _rebuildParser;
+}
+/** Create a new boolean schema builder */
+declare function createBooleanSchema(): BooleanSchemaBuilder;
+
+/**
+ * Chainable enum schema builder for literal string unions.
+ *
+ * @typeParam L - The literal string union type
+ *
+ * @example
+ * ```typescript
+ * const env = t.enum(['development', 'production', 'test'] as const);
+ * // env._parse("production") → { success: true, value: "production" }
+ * // env._parse("staging")    → { success: false, error: "..." }
+ *
+ * // Type is inferred as: SchemaBuilder<"development" | "production" | "test">
+ * ```
+ */
+declare class EnumSchemaBuilder<L extends string> extends SchemaBuilder<L> {
+    private readonly _values;
+    private readonly _valuesArray;
+    private _caseInsensitive;
+    constructor(values: readonly L[]);
+    /** Enable or disable case-insensitive matching */
+    caseInsensitive(enabled?: boolean): EnumSchemaBuilder<L>;
+    /** Get the list of allowed values */
+    get values(): readonly string[];
+    private _rebuildParser;
+}
+/** Create a new enum schema builder */
+declare function createEnumSchema<L extends string>(values: readonly L[]): EnumSchemaBuilder<L>;
+
+/**
+ * Chainable array schema builder.
+ * Splits a string by a configurable separator and validates each element.
+ *
+ * @example
+ * ```typescript
+ * const hosts = t.array().separator(',').minItems(1);
+ * // hosts._parse("a,b,c") → { success: true, value: ["a", "b", "c"] }
+ *
+ * const tags = t.array().separator('|').unique();
+ * // tags._parse("foo|bar|foo") → { success: false, error: "..." }
+ * ```
+ */
+declare class ArraySchemaBuilder extends SchemaBuilder<string[]> {
+    private _separator;
+    private _trimItems;
+    private _filterEmpty;
+    constructor();
+    /** Set the separator character (default: ',') */
+    separator(char: string): ArraySchemaBuilder;
+    /** Trim whitespace from each item after splitting */
+    trimItems(enabled?: boolean): ArraySchemaBuilder;
+    /** Remove empty strings from the result */
+    filterEmpty(enabled?: boolean): ArraySchemaBuilder;
+    /** Require unique items (no duplicates) */
+    unique(): ArraySchemaBuilder;
+    /** Minimum number of items */
+    minItems(n: number): ArraySchemaBuilder;
+    /** Maximum number of items */
+    maxItems(n: number): ArraySchemaBuilder;
+    /** Exact number of items */
+    items(n: number): ArraySchemaBuilder;
+    /** Non-empty array */
+    nonempty(): ArraySchemaBuilder;
+    /** Validate each item against a custom function */
+    itemValidate(fn: (item: string, index: number) => string | null): ArraySchemaBuilder;
+    private _rebuildParser;
+}
+/** Create a new array schema builder */
+declare function createArraySchema(): ArraySchemaBuilder;
+
+/**
+ * Chainable JSON schema builder.
+ * Parses a JSON string into a typed object.
+ *
+ * @typeParam T - The expected JSON output type
+ *
+ * @example
+ * ```typescript
+ * const config = t.json<{ host: string; port: number }>();
+ * // config._parse('{"host":"localhost","port":3000}') → { success: true, value: {...} }
+ *
+ * const configWithSchema = t.json<{ host: string }>().schema((obj) => {
+ *   if (!obj.host) return 'host is required';
+ *   return null;
+ * });
+ * ```
+ */
+declare class JsonSchemaBuilder<T = unknown> extends SchemaBuilder<T> {
+    constructor();
+    /**
+     * Add a custom schema validation function for the parsed object.
+     * Return an error message string, or null if valid.
+     */
+    schema(fn: (value: T) => string | null): JsonSchemaBuilder<T>;
+    /** Require the parsed JSON to be an object (not null, array, or primitive) */
+    object(): JsonSchemaBuilder<T>;
+    /** Require the parsed JSON to be an array */
+    array(): JsonSchemaBuilder<T>;
+    /** Require the parsed JSON to be a string primitive */
+    string(): JsonSchemaBuilder<T>;
+    /** Require the parsed JSON to be a number primitive */
+    number(): JsonSchemaBuilder<T>;
+    /** Require the parsed JSON to be a boolean primitive */
+    boolean(): JsonSchemaBuilder<T>;
+    /** Require a specific top-level key to exist */
+    hasKey(key: string): JsonSchemaBuilder<T>;
+    /** Use a custom JSON reviver during parsing */
+    reviver(reviver: (key: string, value: unknown) => unknown): JsonSchemaBuilder<T>;
+}
+/** Create a new JSON schema builder */
+declare function createJsonSchema<T = unknown>(): JsonSchemaBuilder<T>;
+
+/**
+ * Chainable date schema builder.
+ * Parses various date formats and validates date constraints.
+ *
+ * @example
+ * ```typescript
+ * const deadline = t.date().future();
+ * const birthday = t.date().past();
+ * const launch = t.date().after(new Date('2025-01-01'));
+ * ```
+ */
+declare class DateSchemaBuilder extends SchemaBuilder<Date> {
+    constructor();
+    /** Date must be in the past */
+    past(): DateSchemaBuilder;
+    /** Date must be in the future */
+    future(): DateSchemaBuilder;
+    /** Date must be after the given reference date */
+    after(ref: Date): DateSchemaBuilder;
+    /** Date must be before the given reference date */
+    before(ref: Date): DateSchemaBuilder;
+    /** Date must be a valid date (re-checks, useful after transforms) */
+    valid(): DateSchemaBuilder;
+    /** Use a custom date parser */
+    parse(fn: (raw: string) => Date): DateSchemaBuilder;
+}
+/** Create a new date schema builder */
+declare function createDateSchema(): DateSchemaBuilder;
+
+/**
+ * Chainable regex schema builder.
+ *
+ * @example
+ * ```typescript
+ * const pattern = t.regex();
+ * // pattern._parse("\\d+")       → { success: true, value: /\d+/ }
+ * // pattern._parse("/^\\w+$/gi") → { success: true, value: /^\w+$/gi }
+ * // pattern._parse("[invalid")   → { success: false, error: "Invalid regex: ..." }
+ * ```
+ */
+declare class RegexSchemaBuilder extends SchemaBuilder<RegExp> {
+    constructor();
+    /** Require the regex to have a specific flag */
+    hasFlag(flag: string): RegexSchemaBuilder;
+    /** Require the regex to NOT have a specific flag */
+    noFlag(flag: string): RegexSchemaBuilder;
+    /** Require the regex to be case-insensitive */
+    caseInsensitive(): RegexSchemaBuilder;
+    /** Require the regex to be global */
+    global(): RegexSchemaBuilder;
+    /** Require the regex to be multiline */
+    multiline(): RegexSchemaBuilder;
+    /** Test the regex against a string (validation-only, doesn't change the value) */
+    test(testString: string, expectMatch: boolean): RegexSchemaBuilder;
+}
+/** Create a new regex schema builder */
+declare function createRegexSchema(): RegexSchemaBuilder;
+
+/**
+ * Chainable BigInt schema builder.
+ *
+ * @example
+ * ```typescript
+ * const big = t.bigint().positive().max(999999999999n);
+ * // big._parse("123456789012") → { success: true, value: 123456789012n }
+ * ```
+ */
+declare class BigIntSchemaBuilder extends SchemaBuilder<bigint> {
+    private _radix;
+    constructor();
+    /** Set the radix for parsing (default: 10). Use 16 for hex. */
+    radix(r: number): BigIntSchemaBuilder;
+    /** Minimum value (inclusive) */
+    min(n: bigint): BigIntSchemaBuilder;
+    /** Maximum value (inclusive) */
+    max(n: bigint): BigIntSchemaBuilder;
+    /** Must be positive (> 0) */
+    positive(): BigIntSchemaBuilder;
+    /** Must be negative (< 0) */
+    negative(): BigIntSchemaBuilder;
+    /** Must be non-negative (>= 0) */
+    nonNegative(): BigIntSchemaBuilder;
+    /** Must be one of the specified values */
+    oneOf<const L extends bigint>(values: readonly L[]): BigIntSchemaBuilder;
+    /** Use a custom parse function */
+    parse(fn: (raw: string) => bigint): BigIntSchemaBuilder;
+    private _rebuildParser;
+}
+/** Create a new BigInt schema builder */
+declare function createBigIntSchema(): BigIntSchemaBuilder;
+
+interface UrlValidatorOptions {
+    /** Allowed protocols (default: ['http', 'https']) */
+    protocols?: readonly string[];
+    /** Require a specific hostname */
+    hostname?: string;
+    /** Allowed port numbers */
+    allowedPorts?: readonly number[];
+    /** Whether to allow query strings (default: true) */
+    allowQuery?: boolean;
+    /** Whether to allow fragments (default: true) */
+    allowFragment?: boolean;
+    /** Maximum URL length (default: 2048) */
+    maxLength?: number;
+}
+/** Create a URL schema builder with advanced validation */
+declare function createUrlSchema(opts?: UrlValidatorOptions): SchemaBuilder<URL>;
+
+interface EmailValidatorOptions {
+    /** Maximum email length (default: 254 per RFC 5321) */
+    maxLength?: number;
+    /** Maximum local part length (default: 64 per RFC 5321) */
+    maxLocalLength?: number;
+    /** Allowed TLDs (if specified, restricts to these) */
+    allowedTlds?: readonly string[];
+    /** Blocked domains */
+    blockedDomains?: readonly string[];
+    /** Whether to allow plus addressing (e.g., user+tag@domain.com) */
+    allowPlusAddressing?: boolean;
+}
+/** Create an email schema builder with advanced validation */
+declare function createEmailSchema(opts?: EmailValidatorOptions): SchemaBuilder<string>;
+
+interface IpValidatorOptions {
+    /** IP version to accept: '4', '6', or 'both' (default: 'both') */
+    version?: '4' | '6' | 'both';
+    /** Whether to accept CIDR notation (default: false) */
+    allowCidr?: boolean;
+    /** Whether to accept IPv4-mapped IPv6 addresses (default: true) */
+    allowMappedV4?: boolean;
+}
+/** Create an IP address schema builder */
+declare function createIpSchema(opts?: IpValidatorOptions): SchemaBuilder<string>;
+/** Create an IPv4-only schema builder */
+declare function createIpv4Schema(opts?: Omit<IpValidatorOptions, 'version'>): SchemaBuilder<string>;
+/** Create an IPv6-only schema builder */
+declare function createIpv6Schema(opts?: Omit<IpValidatorOptions, 'version'>): SchemaBuilder<string>;
+
+interface HostnameValidatorOptions {
+    /** Maximum total length (default: 253 per RFC 1035) */
+    maxLength?: number;
+    /** Maximum label length (default: 63 per RFC 1035) */
+    maxLabelLength?: number;
+    /** Whether to allow trailing dot (FQDN, default: false) */
+    allowTrailingDot?: boolean;
+    /** Whether to allow internationalized domain names (default: true) */
+    allowIdn?: boolean;
+    /** Whether to allow underscores in labels (default: false, but common in DNS) */
+    allowUnderscore?: boolean;
+}
+/** Create a hostname schema builder */
+declare function createHostnameSchema(opts?: HostnameValidatorOptions): SchemaBuilder<string>;
+
+interface PortValidatorOptions {
+    /** Whether to include well-known ports (0-1023) — default: true */
+    allowWellKnown?: boolean;
+    /** Whether to include registered ports (1024-49151) — default: true */
+    allowRegistered?: boolean;
+    /** Whether to include dynamic/ephemeral ports (49152-65535) — default: true */
+    allowDynamic?: boolean;
+    /** Whether to allow port 0 (default: false) */
+    allowZero?: boolean;
+    /** Specific allowed ports (overrides range checks if provided) */
+    allowedPorts?: readonly number[];
+}
+/** Create a port schema builder */
+declare function createPortSchema(opts?: PortValidatorOptions): SchemaBuilder<number>;
+
+interface PathValidatorOptions {
+    /** Whether the path must be absolute (start with /) — default: false */
+    absolute?: boolean;
+    /** Whether the path must be relative — default: false */
+    relative?: boolean;
+    /** Whether to allow .. segments — default: false */
+    allowParentTraversal?: boolean;
+    /** Whether to allow home directory (~) — default: false */
+    allowHomeDir?: boolean;
+    /** Maximum path depth (number of segments) — default: unlimited */
+    maxDepth?: number;
+    /** File extension restriction (e.g., ['.json', '.yaml']) */
+    extensions?: readonly string[];
+}
+/** Create a file path schema builder */
+declare function createPathSchema(opts?: PathValidatorOptions): SchemaBuilder<string>;
+
+interface UuidValidatorOptions {
+    /** Require a specific UUID version (1-7) */
+    version?: 1 | 2 | 3 | 4 | 5 | 6 | 7;
+    /** Whether to allow nil UUID (00000000-0000-0000-0000-000000000000) — default: false */
+    allowNil?: boolean;
+    /** Whether to be strict about variant bits — default: true */
+    strictVariant?: boolean;
+}
+/** Create a UUID schema builder */
+declare function createUuidSchema(opts?: UuidValidatorOptions): SchemaBuilder<string>;
+
+interface HexValidatorOptions {
+    /** Whether to allow "0x" prefix — default: false */
+    allowPrefix?: boolean;
+    /** Require "0x" prefix — default: false */
+    requirePrefix?: boolean;
+    /** Exact byte length (number of hex pairs) — e.g., 32 for SHA-256 */
+    byteLength?: number;
+    /** Case requirement: 'lower', 'upper', or 'mixed' (default: 'mixed') */
+    caseSensitive?: 'lower' | 'upper' | 'mixed';
+}
+/** Create a hex string schema builder */
+declare function createHexSchema(opts?: HexValidatorOptions): SchemaBuilder<string>;
+
+interface Base64ValidatorOptions {
+    /** Whether to allow URL-safe characters (- and _ instead of + and /) — default: false */
+    urlSafe?: boolean;
+    /** Whether to require padding (= or ==) — default: false */
+    requirePadding?: boolean;
+    /** Whether to disallow whitespace — default: true */
+    noWhitespace?: boolean;
+    /** Whether to allow empty strings — default: false */
+    allowEmpty?: boolean;
+    /** Minimum decoded byte length — default: none */
+    minBytes?: number;
+    /** Maximum decoded byte length — default: none */
+    maxBytes?: number;
+}
+/** Create a base64 schema builder */
+declare function createBase64Schema(opts?: Base64ValidatorOptions): SchemaBuilder<string>;
+
+interface SemverValidatorOptions {
+    /** Whether to allow prerelease versions (e.g., 1.0.0-alpha.1) — default: true */
+    allowPrerelease?: boolean;
+    /** Whether to allow build metadata (e.g., 1.0.0+build.123) — default: true */
+    allowBuildMetadata?: boolean;
+    /** Whether to allow leading 'v' prefix (e.g., v1.0.0) — default: true */
+    allowVPrefix?: boolean;
+    /** Loose mode — allows non-compliant versions like "1.0" — default: false */
+    loose?: boolean;
+}
+/** Create a semver schema builder */
+declare function createSemverSchema(opts?: SemverValidatorOptions): SchemaBuilder<string>;
+
+interface CronValidatorOptions {
+    /** Whether to allow 6-field expressions (with year) — default: false */
+    allowYear?: boolean;
+    /** Whether to allow 6-field expressions (with seconds) — default: false */
+    allowSeconds?: boolean;
+    /** Whether to allow predefined expressions (e.g., @yearly, @daily) — default: true */
+    allowAliases?: boolean;
+}
+/** Create a cron expression schema builder */
+declare function createCronSchema(opts?: CronValidatorOptions): SchemaBuilder<string>;
+
+interface DurationValidatorOptions {
+    /** Output unit — default: 'ms' */
+    unit?: 'ms' | 's' | 'm' | 'h';
+    /** Maximum duration in milliseconds — default: unlimited */
+    max?: number;
+    /** Minimum duration in milliseconds — default: 0 */
+    min?: number;
+    /** Whether to allow negative durations (e.g., "-5m") — default: false */
+    allowNegative?: boolean;
+}
+/** Create a duration schema builder */
+declare function createDurationSchema(opts?: DurationValidatorOptions): SchemaBuilder<number>;
+
+interface BytesValidatorOptions {
+    /** Whether to use binary units (1024) or decimal units (1000) — default: binary */
+    binary?: boolean;
+    /** Output unit — default: 'bytes' */
+    unit?: 'bytes' | 'kb' | 'mb' | 'gb' | 'tb';
+    /** Maximum byte count — default: unlimited */
+    max?: number;
+    /** Minimum byte count — default: 0 */
+    min?: number;
+}
+/** Create a bytes schema builder */
+declare function createBytesSchema(opts?: BytesValidatorOptions): SchemaBuilder<number>;
+
+interface ColorValidatorOptions {
+    /** Which formats to accept (default: all) */
+    formats?: readonly ('hex' | 'rgb' | 'rgba' | 'hsl' | 'hsla' | 'named')[];
+    /** Whether to accept 3-digit hex (#RGB) — default: true */
+    allowShortHex?: boolean;
+    /** Whether to accept 8-digit hex with alpha (#RRGGBBAA) — default: true */
+    allowAlpha?: boolean;
+}
+/** Create a color schema builder */
+declare function createColorSchema(opts?: ColorValidatorOptions): SchemaBuilder<string>;
+
+interface LocaleValidatorOptions {
+    /** Whether to require a region subtag (e.g., "en-US" not just "en") — default: false */
+    requireRegion?: boolean;
+    /** Allowed language subtags (ISO 639-1 codes) — default: any */
+    allowedLanguages?: readonly string[];
+    /** Whether to accept Unicode extensions (e.g., "en-US-u-ca-buddhist") — default: false */
+    allowExtensions?: boolean;
+}
+/** Create a locale schema builder */
+declare function createLocaleSchema(opts?: LocaleValidatorOptions): SchemaBuilder<string>;
+
+interface TimezoneValidatorOptions {
+    /** Whether to allow UTC offset format (e.g., "UTC+5:30") — default: true */
+    allowOffset?: boolean;
+    /** Whether to allow short timezone names (e.g., "EST", "PST") — default: false */
+    allowShort?: boolean;
+    /** Whether to allow the special "Z" identifier — default: true */
+    allowZ?: boolean;
+}
+/** Create a timezone schema builder */
+declare function createTimezoneSchema(opts?: TimezoneValidatorOptions): SchemaBuilder<string>;
+
+interface CountryValidatorOptions {
+    /** Which format to accept: 'alpha2', 'alpha3', or 'both' — default: 'both' */
+    format?: 'alpha2' | 'alpha3' | 'both';
+    /** Whether to accept numeric codes — default: false */
+    allowNumeric?: boolean;
+}
+/** Create a country code schema builder */
+declare function createCountrySchema(opts?: CountryValidatorOptions): SchemaBuilder<string>;
+
+interface CurrencyValidatorOptions {
+    /** Whether to accept only active currencies — default: true */
+    activeOnly?: boolean;
+    /** Whether to accept cryptocurrency codes (e.g., BTC, ETH) — default: false */
+    allowCrypto?: boolean;
+}
+/** Create a currency code schema builder */
+declare function createCurrencySchema(opts?: CurrencyValidatorOptions): SchemaBuilder<string>;
+
+/**
+ * Apply the required modifier to a schema builder.
+ * This makes the field mandatory — it must be present in the env.
+ *
+ * @param builder - The schema builder to modify
+ * @returns The same builder (for chaining)
+ *
+ * @example
+ * ```typescript
+ * const schema = applyRequired(t.string());
+ * ```
+ */
+declare function applyRequired<T>(builder: SchemaBuilder<T>): SchemaBuilder<T>;
+/**
+ * Check if a schema is marked as required.
+ */
+declare function isRequired<T>(builder: SchemaBuilder<T>): boolean;
+
+/**
+ * Apply the optional modifier to a schema builder.
+ * This makes the field optional — it can be omitted or have an undefined value.
+ *
+ * @param builder - The schema builder to modify
+ * @returns The same builder (for chaining)
+ *
+ * @example
+ * ```typescript
+ * const schema = applyOptional(t.string());
+ * ```
+ */
+declare function applyOptional<T>(builder: SchemaBuilder<T>): SchemaBuilder<T>;
+/**
+ * Check if a schema is marked as optional.
+ */
+declare function isOptional<T>(builder: SchemaBuilder<T>): boolean;
+
+/**
+ * Apply a default value modifier to a schema builder.
+ * When the env variable is not set, the default value will be used.
+ *
+ * @param builder - The schema builder to modify
+ * @param defaultValue - The default value (will be stored as a string for parsing)
+ * @returns The same builder (for chaining)
+ *
+ * @example
+ * ```typescript
+ * const port = applyDefault(t.number(), 3000);
+ * ```
+ */
+declare function applyDefault<T>(builder: SchemaBuilder<T>, defaultValue: T): SchemaBuilder<T>;
+/**
+ * Check if a schema has a default value.
+ */
+declare function hasDefault<T>(builder: SchemaBuilder<T>): boolean;
+/**
+ * Get the default value from a schema, parsed through the schema's parser.
+ */
+declare function getDefaultValue<T>(builder: SchemaBuilder<T>): T | undefined;
+
+/**
+ * Apply the secret modifier to a schema builder.
+ * Secret values will be masked in logs and diagnostic output.
+ *
+ * @param builder - The schema builder to modify
+ * @returns The same builder (for chaining)
+ *
+ * @example
+ * ```typescript
+ * const apiKey = applySecret(t.string());
+ * ```
+ */
+declare function applySecret<T>(builder: SchemaBuilder<T>): SchemaBuilder<T>;
+/**
+ * Check if a schema is marked as secret.
+ */
+declare function isSecret<T>(builder: SchemaBuilder<T>): boolean;
+/**
+ * Mask a value if the schema is marked as secret.
+ * Shows first 4 characters and replaces the rest with asterisks.
+ */
+declare function maskValue<T>(value: T, builder: SchemaBuilder<T>): string;
+
+/**
+ * Apply the deprecated modifier to a schema builder.
+ * Deprecated fields generate warnings during validation.
+ *
+ * @param builder - The schema builder to modify
+ * @param message - The deprecation message (e.g., "Use NEW_VAR instead")
+ * @returns The same builder (for chaining)
+ *
+ * @example
+ * ```typescript
+ * const oldVar = applyDeprecated(t.string(), 'Use NEW_VAR instead');
+ * ```
+ */
+declare function applyDeprecated<T>(builder: SchemaBuilder<T>, message: string): SchemaBuilder<T>;
+/**
+ * Check if a schema is marked as deprecated.
+ */
+declare function isDeprecated<T>(builder: SchemaBuilder<T>): boolean;
+/**
+ * Get the deprecation message from a schema.
+ */
+declare function getDeprecationMessage<T>(builder: SchemaBuilder<T>): string | undefined;
+
+/**
+ * Apply alias names to a schema builder.
+ * Aliases are alternative env variable names that resolve to this schema.
+ *
+ * @param builder - The schema builder to modify
+ * @param names - Alternative variable names
+ * @returns The same builder (for chaining)
+ *
+ * @example
+ * ```typescript
+ * const host = applyAlias(t.string(), 'SERVER_HOST', 'HOSTNAME');
+ * // Both HOST and SERVER_HOST and HOSTNAME will resolve to this schema
+ * ```
+ */
+declare function applyAlias<T>(builder: SchemaBuilder<T>, ...names: string[]): SchemaBuilder<T>;
+/**
+ * Get all aliases for a schema.
+ */
+declare function getAliases<T>(builder: SchemaBuilder<T>): readonly string[];
+/**
+ * Check if a given variable name is an alias for this schema.
+ */
+declare function isAlias<T>(builder: SchemaBuilder<T>, name: string): boolean;
+
+/**
+ * Apply a transform function to a schema builder.
+ * The transform is applied AFTER validation passes.
+ *
+ * @param builder - The schema builder to modify
+ * @param fn - The transform function
+ * @returns The same builder (for chaining)
+ *
+ * @example
+ * ```typescript
+ * const port = applyTransform(t.number(), (v) => v * 1); // identity
+ * const upper = applyTransform(t.string(), (v) => v.toUpperCase());
+ * ```
+ */
+declare function applyTransform<T>(builder: SchemaBuilder<T>, fn: (value: T) => T): SchemaBuilder<T>;
+/**
+ * Compose multiple transform functions into a single function.
+ * Functions are applied from left to right.
+ */
+declare function composeTransforms<T>(...fns: ReadonlyArray<(value: T) => T>): (value: T) => T;
+
+/**
+ * Apply a custom validation function to a schema builder.
+ * The function receives the parsed value and must return:
+ * - `null` or `undefined` if validation passes
+ * - An error message string if validation fails
+ *
+ * @param builder - The schema builder to modify
+ * @param fn - The custom validation function
+ * @returns The same builder (for chaining)
+ *
+ * @example
+ * ```typescript
+ * const password = applyCustom(t.string(), (v) => {
+ *   if (v.length < 12) return 'Password must be at least 12 characters';
+ *   return null;
+ * });
+ * ```
+ */
+declare function applyCustom<T>(builder: SchemaBuilder<T>, fn: (value: T) => string | null): SchemaBuilder<T>;
+/**
+ * Create a validator that checks for a minimum length.
+ */
+declare function minLength<T extends string>(n: number): (value: T) => string | null;
+/**
+ * Create a validator that checks for a maximum length.
+ */
+declare function maxLength<T extends string>(n: number): (value: T) => string | null;
+/**
+ * Create a validator that checks a condition with a custom error message.
+ */
+declare function check<T>(condition: (value: T) => boolean, message: string): (value: T) => string | null;
+/**
+ * Combine multiple validators with short-circuit evaluation.
+ */
+declare function allOf<T>(...validators: ReadonlyArray<(value: T) => string | null>): (value: T) => string | null;
+
+/**
+ * Apply a conditional check to a schema builder.
+ * The schema will only be validated if the condition function returns true.
+ * If the condition returns false, the schema is skipped entirely.
+ *
+ * @param builder - The schema builder to modify
+ * @param check - A function that receives the current env values and returns boolean
+ * @returns The same builder (for chaining)
+ *
+ * @example
+ * ```typescript
+ * const workerThreads = applyConditional(
+ *   t.number().min(1).max(32),
+ *   (env) => env.USE_WORKERS === 'true'
+ * );
+ * ```
+ */
+declare function applyConditional<T>(builder: SchemaBuilder<T>, check: (env: Record<string, unknown>) => boolean): SchemaBuilder<T>;
+/**
+ * Check if a schema has a conditional applied.
+ */
+declare function hasConditional<T>(builder: SchemaBuilder<T>): boolean;
+/**
+ * Evaluate whether a schema's conditional passes given the current env values.
+ * Returns true if the schema should be applied (no conditional or condition passes).
+ */
+declare function shouldApply<T>(builder: SchemaBuilder<T>, env: Record<string, unknown>): boolean;
+
+/**
+ * Apply a description to a schema builder.
+ * Descriptions are used for documentation and error messages.
+ *
+ * @param builder - The schema builder to modify
+ * @param desc - The description text
+ * @returns The same builder (for chaining)
+ *
+ * @example
+ * ```typescript
+ * const host = applyDescription(t.string(), 'The server hostname or IP address');
+ * ```
+ */
+declare function applyDescription<T>(builder: SchemaBuilder<T>, desc: string): SchemaBuilder<T>;
+/**
+ * Get the description from a schema.
+ */
+declare function getDescription<T>(builder: SchemaBuilder<T>): string | undefined;
+/**
+ * Format a schema's description with its type information for documentation.
+ */
+declare function formatSchemaDescription<T>(builder: SchemaBuilder<T>, fieldName: string): string;
+
+/**
+ * The schema builder factory. Use this to create type-safe schemas.
+ *
+ * @example
+ * ```typescript
+ * import { t, defineEnv } from 'ultraenv/schema';
+ *
+ * const env = defineEnv({
+ *   PORT: t.number().port().default(3000),
+ *   HOST: t.string().hostname().default('localhost'),
+ *   NODE_ENV: t.enum(['development', 'production', 'test'] as const),
+ *   DEBUG: t.boolean().optional(),
+ *   ALLOWED_ORIGINS: t.array().separator(','),
+ *   TIMEOUT: t.duration(),
+ *   MAX_SIZE: t.bytes(),
+ *   LOCALE: t.locale(),
+ *   TIMEZONE: t.timezone(),
+ * });
+ * ```
+ */
+declare const t: {
+    readonly string: <T extends string = string>() => StringSchemaBuilder<T>;
+    readonly number: <T extends number = number>() => NumberSchemaBuilder<T>;
+    readonly boolean: () => BooleanSchemaBuilder;
+    readonly enum: <L extends string>(values: readonly L[]) => EnumSchemaBuilder<L>;
+    readonly array: () => ArraySchemaBuilder;
+    readonly json: <T = unknown>() => JsonSchemaBuilder<T>;
+    readonly date: () => DateSchemaBuilder;
+    readonly regex: () => RegexSchemaBuilder;
+    readonly bigint: () => BigIntSchemaBuilder;
+    readonly url: (opts?: UrlValidatorOptions) => SchemaBuilder<URL>;
+    readonly email: (opts?: EmailValidatorOptions) => SchemaBuilder<string>;
+    readonly ip: (opts?: IpValidatorOptions) => SchemaBuilder<string>;
+    readonly ipv4: (opts?: Omit<IpValidatorOptions, "version">) => SchemaBuilder<string>;
+    readonly ipv6: (opts?: Omit<IpValidatorOptions, "version">) => SchemaBuilder<string>;
+    readonly hostname: (opts?: HostnameValidatorOptions) => SchemaBuilder<string>;
+    readonly port: (opts?: PortValidatorOptions) => SchemaBuilder<number>;
+    readonly path: (opts?: PathValidatorOptions) => SchemaBuilder<string>;
+    readonly uuid: (opts?: UuidValidatorOptions) => SchemaBuilder<string>;
+    readonly hex: (opts?: HexValidatorOptions) => SchemaBuilder<string>;
+    readonly base64: (opts?: Base64ValidatorOptions) => SchemaBuilder<string>;
+    readonly semver: (opts?: SemverValidatorOptions) => SchemaBuilder<string>;
+    readonly cron: (opts?: CronValidatorOptions) => SchemaBuilder<string>;
+    readonly duration: (opts?: DurationValidatorOptions) => SchemaBuilder<number>;
+    readonly bytes: (opts?: BytesValidatorOptions) => SchemaBuilder<number>;
+    readonly color: (opts?: ColorValidatorOptions) => SchemaBuilder<string>;
+    readonly locale: (opts?: LocaleValidatorOptions) => SchemaBuilder<string>;
+    readonly timezone: (opts?: TimezoneValidatorOptions) => SchemaBuilder<string>;
+    readonly country: (opts?: CountryValidatorOptions) => SchemaBuilder<string>;
+    readonly currency: (opts?: CurrencyValidatorOptions) => SchemaBuilder<string>;
+};
+/**
+ * Define and validate environment variables from a schema.
+ * Returns a fully typed object where TypeScript infers ALL types from the schema.
+ *
+ * @example
+ * ```typescript
+ * const env = defineEnv({
+ *   PORT: t.number().port().default(3000),
+ *   HOST: t.string().default('localhost'),
+ *   NODE_ENV: t.enum(['development', 'production', 'test'] as const),
+ *   DEBUG: t.boolean().optional(),
+ * });
+ *
+ * // TypeScript knows:
+ * // env.PORT     → number
+ * // env.HOST     → string
+ * // env.NODE_ENV → 'development' | 'production' | 'test'
+ * // env.DEBUG    → boolean | undefined
+ * ```
+ */
+declare function defineEnv<S extends Record<string, SchemaBuilder<unknown>>>(schema: S, vars?: Record<string, string>, options?: EngineOptions): InferSchema<S>;
+/**
+ * Define environment variables without throwing on validation failure.
+ * Returns the result object with valid/warning/error information.
+ */
+declare function tryDefineEnv<S extends Record<string, SchemaBuilder<unknown>>>(schema: S, vars?: Record<string, string>, options?: EngineOptions): {
+    valid: true;
+    values: InferSchema<S>;
+    warnings: readonly ValidationWarningEntry[];
+} | {
+    valid: false;
+    values: Record<string, unknown>;
+    warnings: readonly ValidationWarningEntry[];
+    errors: readonly ValidationErrorEntry[];
+    unknown: readonly string[];
+};
+
+export { ArraySchemaBuilder, type AsyncSchema, type Base64ValidatorOptions, BigIntSchemaBuilder, BooleanSchemaBuilder, type BytesValidatorOptions, type ColorValidatorOptions, type ConditionalConfig, type CountryValidatorOptions, type CronValidatorOptions, type CurrencyValidatorOptions, DateSchemaBuilder, type DurationValidatorOptions, type EmailValidatorOptions, type EngineOptions, type EngineValidationResult, EnumSchemaBuilder, type ExtractDefault, type ExtractType$1 as ExtractType, type HexValidatorOptions, type HostnameValidatorOptions, type InferSchema, type IpValidatorOptions, type IsOptional, JsonSchemaBuilder, type LocaleValidatorOptions, type NoInfer, NumberSchemaBuilder, type OptionalFields, type ParseResult, type PartialSchema, type PathValidatorOptions, type PortValidatorOptions, RegexSchemaBuilder, type RequiredFields, type RequiredSchema, type ResolveOutput$1 as ResolveOutput, SchemaBuilder, type SchemaDefinition, type SchemaMerge, type SchemaMetadata, type SchemaOmit, type SchemaPick, type SchemaValueUnion, type SemverValidatorOptions, StringSchemaBuilder, type TimezoneValidatorOptions, type UrlOptions, type UrlValidatorOptions, type UuidOptions, type UuidValidatorOptions, type ValidationErrorEntry, type ValidationWarningEntry, allOf, applyAlias, applyConditional, applyCustom, applyDefault, applyDeprecated, applyDescription, applyOptional, applyRequired, applySecret, applyTransform, check, composeTransforms, createArraySchema, createBase64Schema, createBigIntSchema, createBooleanSchema, createBytesSchema, createColorSchema, createCountrySchema, createCronSchema, createCurrencySchema, createDateSchema, createDurationSchema, createEmailSchema, createEnumSchema, createHexSchema, createHostnameSchema, createIpSchema, createIpv4Schema, createIpv6Schema, createJsonSchema, createLocaleSchema, createNumberSchema, createPathSchema, createPortSchema, createRegexSchema, createSemverSchema, createStringSchema, createTimezoneSchema, createUrlSchema, createUuidSchema, maxLength as customMaxLength, minLength as customMinLength, defineEnv, formatSchemaDescription, formatValidationResult, getAliases, getDeprecationMessage, getDescription, getDefaultValue as getModDefault, hasConditional, hasDefault, isAlias, isDeprecated, isOptional, isRequired, isSecret, maskValue, shouldApply, t, tryDefineEnv, validate, validateValue };