zod-valid/dist/index.d.ts

Lightweight utilities for flexible Zod schema validation (string, number, array, object, boolean, ISO).

import { z } from 'zod';

type ToValidStringAllow = "none" | "optional" | "nullable" | "nullish";
/**
 * Options to configure the behavior of `toValidString`
 */
type ToValidStringOptions<T extends z.ZodType, K = null> = {
    /**
     * Base Zod schema to apply to the input before coercion.
     * Default is `z.string()`.
     */
    type?: T;
    /**
     * Value to return when the input is invalid or when an allowed empty value
     * (`null`/`undefined`) should be replaced (if `preserve: false`).
     * Default is `null`.
     */
    fallback?: K;
    /**
     * Controls which "empty" values are allowed:
     * - `"none"` — neither `null` nor `undefined` is allowed.
     * - `"optional"` — only `undefined` is allowed.
     * - `"nullable"` — only `null` is allowed.
     * - `"nullish"` — both `null` and `undefined` are allowed.
     *
     * Default is `"nullish"`.
     */
    allow?: ToValidStringAllow;
    /**
     * Determines what happens with allowed empty values:
     * - `true`  — returns the empty value (`null` or `undefined`) as-is.
     * - `false` — replaces the empty value with `fallback`.
     *
     * Default is `true`.
     */
    preserve?: boolean;
};
/**
 * Creates a Zod schema that coerces any value to a string
 * and provides flexible handling of empty values (`null` / `undefined`)
 * and invalid inputs.
 *
 * Behavior:
 * - Converts any input to a string (`String(val)`), unless it is an allowed empty value.
 * - Controls which "empty" values are allowed using the `allow` option:
 *   - `"none"` — neither `null` nor `undefined` are allowed.
 *   - `"optional"` — only `undefined` is considered as allowed empty value.
 *   - `"nullable"` — only `null` is considered as allowed empty value.
 *   - `"nullish"` — both `null` and `undefined` are considered as allowed empty values.
 * - If an empty value is allowed:
 *   - `preserve: true` — returns the empty value as-is.
 *   - `preserve: false` — replaces the empty value with `fallback`.
 * - Any other value is coerced to a string using `String(val)`.
 *
 * @param typeOrOptions Either:
 *   - A base Zod schema to apply (`z.ZodType`), **or**
 *   - An options object (see below).
 *
 * @param [options] Behavior options (if `type` is passed as first argument):
 *   - `type` — base Zod schema to apply. Default `z.string()`.
 *   - `fallback` — value to return when input is invalid or an allowed empty value should be replaced. Default `null`.
 *   - `allow` — which empty values are allowed (`"none"`, `"optional"`, `"nullable"`, `"nullish"`). Default `"nullish"`.
 *   - `preserve` — whether to return allowed empty values as-is (`true`) or replace them with `fallback`. Default `true`.
 *
 * @returns A Zod schema that:
 *   - Coerces valid inputs to string.
 *   - Optionally wraps with `.optional()`, `.nullable()`, or `.nullish()` based on `allow`.
 *
 * @example
 * // Default usage (string coercion with nullish allowed)
 * const schema = toValidString();
 * schema.parse("abc");      // "abc"
 * schema.parse(123);        // "123"
 * schema.parse(null);       // null
 *
 * @example
 * // Pass only options
 * const schema = toValidString({ allow: "optional" });
 * schema.parse(null);       // "null" (null is coerced to string)
 * schema.parse(undefined);  // undefined
 *
 * @example
 * // Pass type first, then options
 * const schema = toValidString(z.string().min(2), { fallback: "N/A", preserve: false });
 * schema.parse("a");        // "N/A"
 * schema.parse("abc");      // "abc"
 * schema.parse(null);       // "N/A"
 *
 * @example
 * // Using custom type in options
 * const schema = toValidString({ type: z.email(), fallback: "empty" });
 * schema.parse("example@host.com"); // "example@host.com"
 * schema.parse("oops");             // "empty"
 * schema.parse(null);               // null
 * schema.parse(undefined);          // undefined
 */
declare function toValidString<T extends z.ZodType, K = null>(type: T, options: Omit<ToValidStringOptions<T, K>, "type"> & {
    allow: "none";
}): z.ZodPipe<z.ZodTransform, z.ZodString>;
declare function toValidString<T extends z.ZodType, K = null>(options: ToValidStringOptions<T, K> & {
    allow: "none";
}): z.ZodPipe<z.ZodTransform, z.ZodString>;
declare function toValidString<T extends z.ZodType, K = null>(type: T, options: Omit<ToValidStringOptions<T, K>, "type"> & {
    preserve: false;
}): z.ZodPipe<z.ZodTransform, z.ZodString | z.ZodType<K>>;
declare function toValidString<T extends z.ZodType, K = null>(options: ToValidStringOptions<T, K> & {
    preserve: false;
}): z.ZodPipe<z.ZodTransform, z.ZodString | z.ZodType<K>>;
declare function toValidString<T extends z.ZodType, K = null>(type: T, options: Omit<ToValidStringOptions<T, K>, "type"> & {
    allow: "optional";
    preserve: false;
}): z.ZodPipe<z.ZodTransform, z.ZodOptional<z.ZodString | z.ZodType<K>>>;
declare function toValidString<T extends z.ZodType, K = null>(options: ToValidStringOptions<T, K> & {
    allow: "optional";
    preserve: false;
}): z.ZodPipe<z.ZodTransform, z.ZodOptional<z.ZodString | z.ZodType<K>>>;
declare function toValidString<T extends z.ZodType, K = null>(type: T, options: Omit<ToValidStringOptions<T, K>, "type"> & {
    allow: "optional";
}): z.ZodPipe<z.ZodTransform, z.ZodOptional<z.ZodString>>;
declare function toValidString<T extends z.ZodType, K = null>(options: ToValidStringOptions<T, K> & {
    allow: "optional";
}): z.ZodPipe<z.ZodTransform, z.ZodOptional<z.ZodString>>;
declare function toValidString<T extends z.ZodType, K = null>(type: T, options: Omit<ToValidStringOptions<T, K>, "type"> & {
    allow: "nullable";
}): z.ZodPipe<z.ZodTransform, z.ZodNullable<z.ZodString>>;
declare function toValidString<T extends z.ZodType, K = null>(options: ToValidStringOptions<T, K> & {
    allow: "nullable";
}): z.ZodPipe<z.ZodTransform, z.ZodNullable<z.ZodString>>;
declare function toValidString<T extends z.ZodType, K = null>(type: T, options?: Omit<ToValidStringOptions<T, K>, "type">): z.ZodPipe<z.ZodTransform, z.ZodOptional<z.ZodNullable<z.ZodString>>>;
declare function toValidString<T extends z.ZodType, K = null>(options?: ToValidStringOptions<T, K>): z.ZodPipe<z.ZodTransform, z.ZodOptional<z.ZodNullable<z.ZodString>>>;

type ToValidNumberAllow = "none" | "optional" | "nullable" | "nullish";
/**
 * Options for configuring the behavior of `toValidNumber`
 */
type ToValidNumberOptions<T extends z.ZodType = z.ZodNumber, K = null> = {
    /**
     * Base Zod schema to apply to the input before coercion.
     * Default is `z.number()`.
     */
    type?: T;
    /**
     * Value to return when the input is invalid or an allowed empty value
     * (`null`/`undefined`) should be replaced (when `preserve: false`).
     * Default is `null`.
     */
    fallback?: K;
    /**
     * Controls which "empty" values are considered allowed:
     * - `"none"` — neither `null` nor `undefined` are allowed.
     * - `"optional"` — only `undefined` is considered allowed.
     * - `"nullable"` — only `null` is considered allowed.
     * - `"nullish"` — both `null` and `undefined` are considered allowed.
     *
     * Default is `"nullish"`.
     */
    allow?: ToValidNumberAllow;
    /**
     * Determines what happens with allowed empty values:
     * - `true`  — returns the empty value (`null` or `undefined`) as-is.
     * - `false` — replaces the empty value with `fallback`.
     *
     * Default is `true`.
     */
    preserve?: boolean;
};
/**
 * Creates a Zod schema that coerces input values to numbers
 * and provides flexible handling of empty values (`null` / `undefined`)
 * and invalid inputs.
 *
 * Behavior:
 * - Converts valid inputs to numbers using `Number(val)`.
 * - Controls which "empty" values are allowed using the `allow` option:
 *   - `"none"` — neither `null` nor `undefined` are allowed.
 *   - `"optional"` — only `undefined` is considered an allowed empty value.
 *   - `"nullable"` — only `null` is considered an allowed empty value.
 *   - `"nullish"` — both `null` and `undefined` are considered allowed empty values.
 * - If an empty value is allowed:
 *   - `preserve: true` — returns the empty value as-is.
 *   - `preserve: false` — replaces the empty value with `fallback`.
 * - Any other value is converted to a number:
 *   - If the result is finite (`Number.isFinite(num)`), it is returned.
 *   - Otherwise, it is replaced with `fallback`.
 *
 * @param typeOrOptions Either:
 *   - A base Zod schema to apply (`z.ZodNumber` or other `z.ZodType`), **or**
 *   - An options object (see below).
 *
 * @param [options] Behavior options (if `type` is passed as first argument):
 *   - `type` — base Zod schema to apply. Default `z.number()`.
 *   - `fallback` — value returned when input is invalid or an allowed empty value should be replaced. Default `null`.
 *   - `allow` — which empty values are allowed (`"none"`, `"optional"`, `"nullable"`, `"nullish"`). Default `"nullish"`.
 *   - `preserve` — whether to return allowed empty values as-is (`true`) or replace them with `fallback`. Default `true`.
 *
 * @returns A ZodPipe schema that:
 *   - Coerces valid inputs to numbers.
 *   - Optionally wraps with `.optional()`, `.nullable()`, or `.nullish()` based on `allow`.
 *
 * @example
 * // Default usage
 * const schema = toValidNumber();
 * schema.parse(42);        // 42
 * schema.parse("123");     // 123
 * schema.parse(null);      // null (allow="nullish", preserve=true)
 *
 * @example
 * // Passing options only
 * const schemaOpt = toValidNumber({ allow: "optional" });
 * schemaOpt.parse(null);      // null → fallback if preserve=false
 * schemaOpt.parse(undefined); // undefined
 *
 * @example
 * // Passing type first, options second
 * const schemaTyped = toValidNumber(z.number().min(10), { fallback: 0 });
 * schemaTyped.parse(5);    // 0 (invalid, replaced with fallback)
 * schemaTyped.parse(20);   // 20
 *
 * @example
 * // With allow="nullish" and custom fallback
 * const schemaFallback = toValidNumber({ allow: "nullish", fallback: 99, preserve: false });
 * schemaFallback.parse("abc");     // 99
 * schemaFallback.parse(null);      // 99
 * schemaFallback.parse(undefined); // 99
 */
declare function toValidNumber<T extends z.ZodType = z.ZodNumber, K = null>(type: T, options: Omit<ToValidNumberOptions<T, K>, "type"> & {
    allow: "none";
}): z.ZodPipe<z.ZodTransform, T extends z.ZodNumber ? z.ZodNumber | (K extends null | undefined ? z.ZodType<z.infer<T>> : z.ZodType<K>) : K extends null | undefined ? z.ZodType<z.infer<T>> : z.ZodType<K>>;
declare function toValidNumber<T extends z.ZodType = z.ZodNumber, K = null>(options: ToValidNumberOptions<T, K> & {
    allow: "none";
}): z.ZodPipe<z.ZodTransform, T extends z.ZodNumber ? z.ZodNumber | (K extends null | undefined ? z.ZodType<z.infer<T>> : z.ZodType<K>) : K extends null | undefined ? z.ZodType<z.infer<T>> : z.ZodType<K>>;
declare function toValidNumber<T extends z.ZodType = z.ZodNumber, K = null>(type: T, options: Omit<ToValidNumberOptions<T, K>, "type"> & {
    preserve: false;
}): z.ZodPipe<z.ZodTransform, T extends z.ZodNumber ? z.ZodNumber | z.ZodType<K> : z.ZodType<K>>;
declare function toValidNumber<T extends z.ZodType = z.ZodNumber, K = null>(options: ToValidNumberOptions<T, K> & {
    preserve: false;
}): z.ZodPipe<z.ZodTransform, T extends z.ZodNumber ? z.ZodNumber | z.ZodType<K> : z.ZodType<K>>;
declare function toValidNumber<T extends z.ZodType = z.ZodNumber, K = null>(type: T, options: Omit<ToValidNumberOptions<T, K>, "type"> & {
    allow: "optional";
}): z.ZodPipe<z.ZodTransform, z.ZodOptional<T extends z.ZodNumber ? z.ZodNumber | z.ZodType<K> : z.ZodType<K>>>;
declare function toValidNumber<T extends z.ZodType = z.ZodNumber, K = null>(options: ToValidNumberOptions<T, K> & {
    allow: "optional";
}): z.ZodPipe<z.ZodTransform, z.ZodOptional<T extends z.ZodNumber ? z.ZodNumber | z.ZodType<K> : z.ZodType<K>>>;
declare function toValidNumber<T extends z.ZodType = z.ZodNumber, K = null>(type: T, options: Omit<ToValidNumberOptions<T, K>, "type"> & {
    allow: "nullable";
}): z.ZodPipe<z.ZodTransform, z.ZodNullable<T extends z.ZodNumber ? z.ZodNumber | z.ZodType<K> : z.ZodType<K>>>;
declare function toValidNumber<T extends z.ZodType = z.ZodNumber, K = null>(options: ToValidNumberOptions<T, K> & {
    allow: "nullable";
}): z.ZodPipe<z.ZodTransform, z.ZodNullable<T extends z.ZodNumber ? z.ZodNumber | z.ZodType<K> : z.ZodType<K>>>;
declare function toValidNumber<T extends z.ZodType = z.ZodNumber, K = null>(type: T, options?: Omit<ToValidNumberOptions<T, K>, "type">): z.ZodPipe<z.ZodTransform, z.ZodOptional<z.ZodNullable<T extends z.ZodNumber ? z.ZodNumber | z.ZodType<K> : z.ZodType<K>>>>;
declare function toValidNumber<T extends z.ZodType = z.ZodNumber, K = null>(options?: ToValidNumberOptions<T, K>): z.ZodPipe<z.ZodTransform, z.ZodOptional<z.ZodNullable<T extends z.ZodNumber ? z.ZodNumber | z.ZodType<K> : z.ZodType<K>>>>;

type ToValidBooleanAllow = "none" | "optional" | "nullable" | "nullish";
/**
 * Options for configuring the behavior of `toValidBoolean`
 */
type ToValidBooleanOptions<T extends z.ZodType = z.ZodBoolean, K = null> = {
    /**
     * Base Zod schema to apply to the input before coercion.
     * Default is `z.boolean()`.
     */
    type?: T;
    /**
     * Value to return when the input is invalid or an allowed empty value
     * (`null`/`undefined`) should be replaced (when `preserve: false`).
     * Default is `null`.
     */
    fallback?: K;
    /**
     * Controls which "empty" values are considered allowed:
     * - `"none"` — neither `null` nor `undefined` are allowed.
     * - `"optional"` — only `undefined` is considered allowed.
     * - `"nullable"` — only `null` is considered allowed.
     * - `"nullish"` — both `null` and `undefined` are considered allowed.
     *
     * Default is `"nullish"`.
     */
    allow?: ToValidBooleanAllow;
    /**
     * Determines what happens with allowed empty values:
     * - `true`  — returns the empty value (`null` or `undefined`) as-is.
     * - `false` — replaces the empty value with `fallback`.
     *
     * Default is `true`.
     */
    preserve?: boolean;
};
/**
 * Creates a Zod schema that coerces input to boolean values
 * and provides flexible handling of empty values (`null` / `undefined`)
 * and invalid inputs.
 *
 * Behavior:
 * - Converts strings like `"true"`/`"false"` (case-insensitive) to boolean.
 * - Converts numbers to boolean (`0` → `false`, others → `true`).
 * - Objects: non-empty objects → `true`, empty objects → `false`.
 * - Controls which "empty" values are allowed using the `allow` option:
 *   - `"none"` — neither `null` nor `undefined` are allowed.
 *   - `"optional"` — only `undefined` is considered an allowed empty value.
 *   - `"nullable"` — only `null` is considered an allowed empty value.
 *   - `"nullish"` — both `null` and `undefined` are considered allowed empty values.
 * - If an empty value is allowed:
 *   - `preserve: true` — returns the empty value as-is.
 *   - `preserve: false` — replaces the empty value with `fallback`.
 * - Any other invalid value is coerced to boolean following the rules above.
 *
 * @param typeOrOptions Either:
 *   - A base Zod schema to apply (`z.ZodBoolean` or other `z.ZodType`), **or**
 *   - An options object (see below).
 *
 * @param [options] Behavior options (if `type` is passed as first argument):
 *   - `type` — base Zod schema to apply. Default `z.boolean()`.
 *   - `fallback` — value returned when input is invalid or an allowed empty value should be replaced. Default `null`.
 *   - `allow` — which empty values are allowed (`"none"`, `"optional"`, `"nullable"`, `"nullish"`). Default `"nullish"`.
 *   - `preserve` — whether to return allowed empty values as-is (`true`) or replace them with `fallback`. Default `true`.
 *
 * @returns A ZodPipe schema that:
 *   - Coerces valid inputs to boolean.
 *   - Optionally wraps with `.optional()`, `.nullable()`, or `.nullish()` based on `allow`.
 *
 * @example
 * // Default usage
 * const schema = toValidBoolean();
 * schema.parse("true");   // true
 * schema.parse("FALSE");  // false
 * schema.parse(1);        // true
 * schema.parse(0);        // false
 * schema.parse(null);     // null (allow="nullish", preserve=true)
 *
 * @example
 * // Passing options only
 * const schemaOpt = toValidBoolean({ allow: "optional" });
 * schemaOpt.parse(null);      // null → fallback if preserve=false
 * schemaOpt.parse(undefined); // undefined
 *
 * @example
 * // Passing type first, options second
 * const schemaTyped = toValidBoolean(z.boolean(), { fallback: false });
 * schemaTyped.parse("true"); // true
 * schemaTyped.parse("oops"); // false
 *
 * @example
 * // With allow="nullish" and custom fallback
 * const schemaFallback = toValidBoolean({ allow: "nullish", fallback: false, preserve: false });
 * schemaFallback.parse(null);      // false
 * schemaFallback.parse(undefined); // false
 * schemaFallback.parse("oops");    // false
 */
declare function toValidBoolean<T extends z.ZodType = z.ZodBoolean, K = null>(type: T, options: Omit<ToValidBooleanOptions<T, K>, "type"> & {
    allow: "none";
}): z.ZodPipe<z.ZodTransform, z.ZodType<z.infer<T>>>;
declare function toValidBoolean<T extends z.ZodType = z.ZodBoolean, K = null>(options: ToValidBooleanOptions<T, K> & {
    allow: "none";
}): z.ZodPipe<z.ZodTransform, z.ZodType<z.infer<T>>>;
declare function toValidBoolean<T extends z.ZodType = z.ZodBoolean, K = null>(type: T, options: Omit<ToValidBooleanOptions<T, K>, "type"> & {
    preserve: false;
}): z.ZodPipe<z.ZodTransform, z.ZodType<z.infer<T>> | z.ZodType<K>>;
declare function toValidBoolean<T extends z.ZodType = z.ZodBoolean, K = null>(options: ToValidBooleanOptions<T, K> & {
    preserve: false;
}): z.ZodPipe<z.ZodTransform, z.ZodType<z.infer<T>> | z.ZodType<K>>;
declare function toValidBoolean<T extends z.ZodType = z.ZodBoolean, K = null>(type: T, options: Omit<ToValidBooleanOptions<T, K>, "type"> & {
    allow: "optional";
}): z.ZodPipe<z.ZodTransform, z.ZodOptional<z.ZodType<z.infer<T>>>>;
declare function toValidBoolean<T extends z.ZodType = z.ZodBoolean, K = null>(options: ToValidBooleanOptions<T, K> & {
    allow: "optional";
}): z.ZodPipe<z.ZodTransform, z.ZodOptional<z.ZodType<z.infer<T>>>>;
declare function toValidBoolean<T extends z.ZodType = z.ZodBoolean, K = null>(type: T, options: Omit<ToValidBooleanOptions<T, K>, "type"> & {
    allow: "nullable";
}): z.ZodPipe<z.ZodTransform, z.ZodNullable<z.ZodType<z.infer<T>>>>;
declare function toValidBoolean<T extends z.ZodType = z.ZodBoolean, K = null>(options: ToValidBooleanOptions<T, K> & {
    allow: "nullable";
}): z.ZodPipe<z.ZodTransform, z.ZodNullable<z.ZodType<z.infer<T>>>>;
declare function toValidBoolean<T extends z.ZodType = z.ZodBoolean, K = null>(type: T, options?: Omit<ToValidBooleanOptions<T, K>, "type">): z.ZodPipe<z.ZodTransform, z.ZodOptional<z.ZodNullable<z.ZodType<z.infer<T>>>>>;
declare function toValidBoolean<T extends z.ZodType = z.ZodBoolean, K = null>(options?: ToValidBooleanOptions<T, K>): z.ZodPipe<z.ZodTransform, z.ZodOptional<z.ZodNullable<z.ZodType<z.infer<T>>>>>;

type ToValidISOAllow = "none" | "optional" | "nullable" | "nullish";
/**
 * Options for configuring the behavior of `toValidISO`
 */
type ToValidIsoOptions<T extends z.ZodType = z.ZodISODateTime, K = null> = {
    /**
     * Base Zod schema to apply to the input before coercion.
     * Default is `z.iso.datetime()`.
     */
    type?: T;
    /**
     * Value to return when the input is invalid or an allowed empty value
     * (`null`/`undefined`) should be replaced (when `preserve: false`).
     * Default is `null`.
     */
    fallback?: K;
    /**
     * Controls which "empty" values are considered allowed:
     * - `"none"` — neither `null` nor `undefined` are allowed.
     * - `"optional"` — only `undefined` is considered allowed.
     * - `"nullable"` — only `null` is considered allowed.
     * - `"nullish"` — both `null` and `undefined` are considered allowed.
     *
     * Default is `"nullish"`.
     */
    allow?: ToValidISOAllow;
    /**
     * Determines what happens with allowed empty values:
     * - `true`  — returns the empty value (`null` or `undefined`) as-is.
     * - `false` — replaces the empty value with `fallback`.
     *
     * Default is `true`.
     */
    preserve?: boolean;
};
/**
 * Creates a Zod schema that coerces input to ISO 8601 date strings
 * and provides flexible handling of empty values (`null` / `undefined`)
 * and invalid inputs.
 *
 * Behavior:
 * - Converts valid string inputs to ISO 8601 format (`YYYY-MM-DDTHH:mm:ssZ`).
 * - Controls which "empty" values are allowed using the `allow` option:
 *   - `"none"` — neither `null` nor `undefined` are allowed.
 *   - `"optional"` — only `undefined` is considered an allowed empty value.
 *   - `"nullable"` — only `null` is considered an allowed empty value.
 *   - `"nullish"` — both `null` and `undefined` are considered allowed empty values.
 * - If an empty value is allowed:
 *   - `preserve: true` — returns the empty value as-is.
 *   - `preserve: false` — replaces the empty value with `fallback`.
 * - Any other value is processed:
 *   - Strings are parsed as dates. Invalid dates return `fallback`.
 *   - Non-strings return `fallback`.
 *
 * @param typeOrOptions Either:
 *   - A base Zod schema to apply (`z.ZodISODateTime` or other `z.ZodType`), **or**
 *   - An options object (see below).
 *
 * @param [options] Behavior options (if `type` is passed as first argument):
 *   - `type` — base Zod schema to apply. Default `z.iso.datetime()`.
 *   - `fallback` — value returned when input is invalid or an allowed empty value should be replaced. Default `null`.
 *   - `allow` — which empty values are allowed (`"none"`, `"optional"`, `"nullable"`, `"nullish"`). Default `"nullish"`.
 *   - `preserve` — whether to return allowed empty values as-is (`true`) or replace them with `fallback`. Default `true`.
 *
 * @returns A ZodPipe schema that:
 *   - Coerces valid inputs to ISO 8601 strings.
 *   - Optionally wraps with `.optional()`, `.nullable()`, or `.nullish()` based on `allow`.
 *
 * @example
 * // Default usage
 * const schema = toValidISO();
 * schema.parse("2025-09-02T10:00:00Z"); // "2025-09-02T10:00:00Z"
 * schema.parse(null);                   // null (allow="nullish", preserve=true)
 *
 * @example
 * // Passing options only
 * const schemaOpt = toValidISO({ allow: "optional" });
 * schemaOpt.parse(null);      // null → fallback if preserve=false
 * schemaOpt.parse(undefined); // undefined
 *
 * @example
 * // Passing type first, options second
 * const schemaTyped = toValidISO(z.string().datetime(), { fallback: "1970-01-01T00:00:00Z" });
 * schemaTyped.parse("invalid");    // "1970-01-01T00:00:00Z"
 * schemaTyped.parse("2025-09-11"); // "2025-09-11T00:00:00.000Z"
 *
 * @example
 * // With allow="nullish" and custom fallback
 * const schemaFallback = toValidISO({ allow: "nullish", fallback: "N/A", preserve: false });
 * schemaFallback.parse("abc");     // "N/A"
 * schemaFallback.parse(null);      // "N/A"
 * schemaFallback.parse(undefined); // "N/A"
 */
declare function toValidISO<T extends z.ZodType = z.ZodISODateTime, K = null>(type: T, options: Omit<ToValidIsoOptions<T, K>, "type"> & {
    allow: "none";
}): z.ZodPipe<z.ZodTransform, z.ZodType<NonNullable<z.infer<T> | K>>>;
declare function toValidISO<T extends z.ZodType = z.ZodISODateTime, K = null>(options: ToValidIsoOptions<T, K> & {
    allow: "none";
}): z.ZodPipe<z.ZodTransform, z.ZodType<NonNullable<z.infer<T> | K>>>;
declare function toValidISO<T extends z.ZodType = z.ZodISODateTime, K = null>(type: T, options: Omit<ToValidIsoOptions<T, K>, "type"> & {
    preserve: false;
}): z.ZodPipe<z.ZodTransform, z.ZodType<z.infer<T> | K>>;
declare function toValidISO<T extends z.ZodType = z.ZodISODateTime, K = null>(options: ToValidIsoOptions<T, K> & {
    preserve: false;
}): z.ZodPipe<z.ZodTransform, z.ZodType<z.infer<T> | K>>;
declare function toValidISO<T extends z.ZodType = z.ZodISODateTime, K = null>(type: T, options: Omit<ToValidIsoOptions<T, K>, "type"> & {
    allow: "optional";
}): z.ZodPipe<z.ZodTransform, z.ZodOptional<z.ZodType<z.infer<T> | K>>>;
declare function toValidISO<T extends z.ZodType = z.ZodISODateTime, K = null>(options: ToValidIsoOptions<T, K> & {
    allow: "optional";
}): z.ZodPipe<z.ZodTransform, z.ZodOptional<z.ZodType<z.infer<T> | K>>>;
declare function toValidISO<T extends z.ZodType = z.ZodISODateTime, K = null>(type: T, options: Omit<ToValidIsoOptions<T, K>, "type"> & {
    allow: "nullable";
}): z.ZodPipe<z.ZodTransform, z.ZodNullable<z.ZodType<z.infer<T> | K>>>;
declare function toValidISO<T extends z.ZodType = z.ZodISODateTime, K = null>(options: ToValidIsoOptions<T, K> & {
    allow: "nullable";
}): z.ZodPipe<z.ZodTransform, z.ZodNullable<z.ZodType<z.infer<T> | K>>>;
declare function toValidISO<T extends z.ZodType = z.ZodISODateTime, K = null>(type: T, options?: Omit<ToValidIsoOptions<T, K>, "type">): z.ZodPipe<z.ZodTransform, z.ZodOptional<z.ZodNullable<z.ZodType<z.infer<T> | K>>>>;
declare function toValidISO<T extends z.ZodType = z.ZodISODateTime, K = null>(options?: ToValidIsoOptions<T, K>): z.ZodPipe<z.ZodTransform, z.ZodOptional<z.ZodNullable<z.ZodType<z.infer<T> | K>>>>;

type ToValidArrayAllow = "none" | "optional" | "nullable" | "nullish";
/**
 * Options for configuring the behavior of `toValidArray`
 */
type ToValidArrayOptions<T extends z.ZodType, K = [], S extends boolean = true> = {
    /**
     * Base Zod schema for the array elements.
     */
    type?: T;
    /**
     * Value to return when the input is invalid or an allowed empty value
     * (`null`/`undefined`) should be replaced (when `preserve: false`).
     * Default is `[]`.
     */
    fallback?: K;
    /**
     * Controls which "empty" values are considered allowed in the array:
     * - `"none"` — neither `null` nor `undefined` are allowed.
     * - `"optional"` — only `undefined` is considered allowed.
     * - `"nullable"` — only `null` is considered allowed.
     * - `"nullish"` — both `null` and `undefined` are considered allowed.
     *
     * Default is `"nullish"`.
     */
    allow?: ToValidArrayAllow;
    /**
     * Determines what happens with allowed empty values:
     * - `true`  — returns the empty value (`null` or `undefined`) as-is.
     * - `false` — replaces the empty value with `fallback`.
     *
     * Default is `true`.
     */
    preserve?: boolean;
    /**
     * Whether to strictly enforce the element schema:
     * - `true` — removes any elements that do **not** pass the `type` schema (invalid elements).
     *            Also removes `null` and `undefined` values, even if allowed by `allow`.
     *            **Does not remove fallback values** if they are not `null` or `undefined`.
     * - `false` — invalid elements and allowed empty values are preserved (or replaced by `fallback` if `preserve: false`).
     *
     * Default is `true`.
     */
    strict?: S;
};
/**
 * Creates a Zod schema that ensures input is an array of elements
 * matching a given schema (`type`), with flexible handling of
 * empty (`null` / `undefined`) and invalid values.
 *
 * Behavior:
 * - If input is not an array and not an allowed empty value, it is replaced with `fallback`.
 * - Controls which empty values are allowed using the `allow` option:
 *   - `"none"` — neither `null` nor `undefined` are allowed.
 *   - `"optional"` — only `undefined` is considered an allowed empty value.
 *   - `"nullable"` — only `null` is considered an allowed empty value.
 *   - `"nullish"` — both `null` and `undefined` are considered allowed empty values.
 * - If an empty value is allowed:
 *   - `preserve: true` — returns the empty value as-is.
 *   - `preserve: false` — replaces the empty value with `fallback`.
 * - If `strict: true`:
 *   - invalid elements are removed.
 *   - `null` and `undefined` are removed regardless of `allow`.
 *   - fallback values are preserved (if they are not `null`/`undefined`).
 * - If `strict: false`:
 *   - invalid elements are kept as-is (or replaced by `fallback` if `preserve: false`).
 *
 * @param typeOrOptions Either:
 *   - A base Zod schema for array elements (e.g. `z.string()`), **or**
 *   - An options object (see below).
 *
 * @param [options] Behavior options (if `type` is passed as first argument):
 *   - `type` — schema for array elements. Default is `z.never()`.
 *   - `fallback` — value returned instead of invalid input or replaced empty value. Default `null`.
 *   - `allow` — which empty values are allowed (`"none"`, `"optional"`, `"nullable"`, `"nullish"`). Default `"nullish"`.
 *   - `preserve` — whether to return allowed empty values as-is (`true`) or replace them with `fallback`. Default `true`.
 *   - `strict` — whether to strictly enforce element schema (`true` removes invalid items). Default `true`.
 *
 * @returns A ZodPipe schema that validates arrays and applies the described rules.
 *
 * @example
 * // Default usage (options only)
 * const schema = toValidArray({ type: z.string() });
 * schema.parse(["a", "b"]); // ["a", "b"]
 * schema.parse(null);       // null (allow="nullish", preserve=true)
 *
 * @example
 * // Type first, options second
 * const schemaTyped = toValidArray(z.number(), { allow: "optional" });
 * schemaTyped.parse([1, 2]);     // [1, 2]
 * schemaTyped.parse(undefined);  // undefined
 *
 * @example
 * // With custom fallback
 * const schemaFallback = toValidArray({ type: z.number(), allow: "nullable", fallback: [], preserve: false });
 * schemaFallback.parse("oops"); // []
 * schemaFallback.parse(null);   // []
 *
 * @example
 * // Strict mode
 * const strictSchema = toValidArray({ type: z.number(), strict: true });
 * strictSchema.parse([1, "x", 2, null, undefined]); // [1, 2]
 */
declare function toValidArray<T extends z.ZodType, K = [], S extends boolean = true>(type: T, options: Omit<ToValidArrayOptions<T, K, S>, "type"> & {
    allow: "none";
}): z.ZodPipe<z.ZodTransform, z.ZodArray<S extends true ? z.ZodType<NonNullable<z.infer<T>>> : T> | (K extends never[] ? z.ZodArray<S extends true ? z.ZodType<NonNullable<z.infer<T>>> : T> : K extends null | undefined ? z.ZodArray<S extends true ? z.ZodType<NonNullable<z.infer<T>>> : T> : z.ZodType<K>)>;
declare function toValidArray<T extends z.ZodType, K = [], S extends boolean = true>(options: ToValidArrayOptions<T, K, S> & {
    allow: "none";
}): z.ZodPipe<z.ZodTransform, z.ZodArray<S extends true ? z.ZodType<NonNullable<z.infer<T>>> : T> | (K extends never[] ? z.ZodArray<S extends true ? z.ZodType<NonNullable<z.infer<T>>> : T> : K extends null | undefined ? z.ZodArray<S extends true ? z.ZodType<NonNullable<z.infer<T>>> : T> : z.ZodType<K>)>;
declare function toValidArray<T extends z.ZodType, K = [], S extends boolean = true>(type: T, options: Omit<ToValidArrayOptions<T, K, S>, "type"> & {
    preserve: false;
}): z.ZodPipe<z.ZodTransform, z.ZodArray<S extends true ? z.ZodType<NonNullable<z.infer<T>>> : T> | (K extends never[] ? z.ZodArray<S extends true ? z.ZodType<NonNullable<z.infer<T>>> : T> : z.ZodType<K>)>;
declare function toValidArray<T extends z.ZodType, K = [], S extends boolean = true>(options: ToValidArrayOptions<T, K, S> & {
    preserve: false;
}): z.ZodPipe<z.ZodTransform, z.ZodArray<S extends true ? z.ZodType<NonNullable<z.infer<T>>> : T> | (K extends never[] ? z.ZodArray<S extends true ? z.ZodType<NonNullable<z.infer<T>>> : T> : z.ZodType<K>)>;
declare function toValidArray<T extends z.ZodType, K = [], S extends boolean = true>(type: T, options: Omit<ToValidArrayOptions<T, K, S>, "type"> & {
    allow: "optional";
}): z.ZodPipe<z.ZodTransform, K extends never[] ? z.ZodOptional<z.ZodArray<S extends true ? z.ZodType<NonNullable<z.infer<T>>> : T>> : z.ZodOptional<z.ZodUnion<[
    z.ZodArray<S extends true ? z.ZodType<NonNullable<z.infer<T>>> : T>,
    z.ZodCustom<K, K>
]>>>;
declare function toValidArray<T extends z.ZodType, K = [], S extends boolean = true>(options: ToValidArrayOptions<T, K, S> & {
    allow: "optional";
}): z.ZodPipe<z.ZodTransform, K extends never[] ? z.ZodOptional<z.ZodArray<S extends true ? z.ZodType<NonNullable<z.infer<T>>> : T>> : z.ZodOptional<z.ZodUnion<[
    z.ZodArray<S extends true ? z.ZodType<NonNullable<z.infer<T>>> : T>,
    z.ZodCustom<K, K>
]>>>;
declare function toValidArray<T extends z.ZodType, K = [], S extends boolean = true>(type: T, options: Omit<ToValidArrayOptions<T, K, S>, "type"> & {
    allow: "nullable";
}): z.ZodPipe<z.ZodTransform, K extends never[] ? z.ZodNullable<z.ZodArray<S extends true ? z.ZodType<NonNullable<z.infer<T>>> : T>> : z.ZodNullable<z.ZodUnion<[
    z.ZodArray<S extends true ? z.ZodType<NonNullable<z.infer<T>>> : T>,
    z.ZodCustom<K, K>
]>>>;
declare function toValidArray<T extends z.ZodType, K = [], S extends boolean = true>(options: ToValidArrayOptions<T, K, S> & {
    allow: "nullable";
}): z.ZodPipe<z.ZodTransform, K extends never[] ? z.ZodNullable<z.ZodArray<S extends true ? z.ZodType<NonNullable<z.infer<T>>> : T>> : z.ZodNullable<z.ZodUnion<[
    z.ZodArray<S extends true ? z.ZodType<NonNullable<z.infer<T>>> : T>,
    z.ZodCustom<K, K>
]>>>;
declare function toValidArray<T extends z.ZodType, K = [], S extends boolean = true>(type: T, options?: Omit<ToValidArrayOptions<T, K, S>, "type">): z.ZodPipe<z.ZodTransform, K extends never[] ? z.ZodOptional<z.ZodNullable<z.ZodArray<S extends true ? z.ZodType<NonNullable<z.infer<T>>> : T>>> : z.ZodOptional<z.ZodNullable<z.ZodUnion<[
    z.ZodArray<S extends true ? z.ZodType<NonNullable<z.infer<T>>> : T>,
    z.ZodCustom<K, K>
]>>>>;
declare function toValidArray<T extends z.ZodType, K = [], S extends boolean = true>(options?: ToValidArrayOptions<T, K, S>): z.ZodPipe<z.ZodTransform, K extends never[] ? z.ZodOptional<z.ZodNullable<z.ZodArray<S extends true ? z.ZodType<NonNullable<z.infer<T>>> : T>>> : z.ZodOptional<z.ZodNullable<z.ZodUnion<[
    z.ZodArray<S extends true ? z.ZodType<NonNullable<z.infer<T>>> : T>,
    z.ZodCustom<K, K>
]>>>>;

type ToValidObjectAllow = "none" | "optional" | "nullable" | "nullish";
/**
 * Options for configuring the behavior of `toValidObject`.
 */
type ToValidObjectOptions<T extends z.ZodObject | z.ZodEnum = z.ZodObject, K = null> = {
    /**
     * Base Zod schema used to validate plain objects.
     *
     * Defaults to `z.object({}).catchall(z.any())` (accepts any key-value pairs).
     */
    type?: T;
    /**
     * Replacement value returned when the input is invalid, or when an allowed
     * empty value (`null`/`undefined`) is replaced because `preserve` is `false`.
     *
     * Defaults to `null`.
     */
    fallback?: K;
    /**
     * Defines which "empty" values are considered allowed:
     * - `"none"`     — neither `null` nor `undefined` are allowed.
     * - `"optional"` — only `undefined` is allowed.
     * - `"nullable"` — only `null` is allowed.
     * - `"nullish"`  — both `null` and `undefined` are allowed.
     *
     * Defaults to `"nullish"`.
     */
    allow?: ToValidObjectAllow;
    /**
     * Controls how allowed empty values are handled:
     * - `true`  — return the empty value (`null` or `undefined`) as-is.
     * - `false` — replace the empty value with `fallback`.
     *
     * Defaults to `true`.
     */
    preserve?: boolean;
};
/**
 * Creates a Zod schema that ensures the input is a **plain object**
 * (validated by `type`), with flexible handling of empty values
 * (`null` / `undefined`) and a fallback value for invalid cases.
 *
 * Behavior:
 * - If the input is a plain object (`{}`), it is validated against `type`.
 * - If the input is not an object:
 *   - If it matches the allowed `allow` values (`null` / `undefined`),
 *     then either the original value is returned (`preserve: true`) or it is replaced
 *     with `fallback` (`preserve: false`).
 *   - Otherwise, the value is replaced with `fallback`.
 *
 * @param typeOrOptions Either:
 *   - A base Zod schema to apply (`z.ZodObject` or `z.ZodEnum`), **or**
 *   - An options object (see below).
 *
 * @param [options] Behavior options (if `type` is passed as first argument):
 * - `type` — Base Zod schema for validating objects.
 *   Default: `z.object({}).catchall(z.any())` (any plain object).
 * - `fallback` — Value returned instead of invalid input or replaced empty input (`preserve: false`).
 *   Default: `null`.
 * - `allow` — Which empty values are considered valid:
 *   - `"none"`     — neither `null` nor `undefined` are allowed.
 *   - `"optional"` — only `undefined` is allowed.
 *   - `"nullable"` — only `null` is allowed.
 *   - `"nullish"`  — both `null` and `undefined` are allowed.
 *   Default: `"nullish"`.
 * - `preserve` — What to do with allowed empty values:
 *   - `true`  — return them as-is.
 *   - `false` — replace them with `fallback`.
 *   Default: `true`.
 *
 * @returns A ZodPipe schema that:
 * - Validates plain objects using `type`.
 * - Optionally wraps with `.optional()`, `.nullable()`, or `.nullish()` depending on `allow`.
 * - Replaces or preserves empty values according to `preserve` and `fallback`.
 *
 * @example
 * // Passing options only
 * const schemaNum = toValidObject({ type: z.object({ x: z.number() }) });
 * schemaNum.parse({ x: 42 });     // { x: 42 }
 * schemaNum.parse({ x: "oops" }); // null (invalid, replaced with fallback)
 *
 * @example
 * // Passing type first, options second
 * const schemaStrict = toValidObject(z.object({ id: z.string() }), { allow: "nullish" });
 * schemaStrict.parse({ id: "abc" }); // { id: "abc" }
 * schemaStrict.parse({ id: 123 });   // null (invalid, fallback applied)
 *
 * @example
 * // With allow="optional"
 * const RoleEnum = z.enum(["admin", "user", "guest"]);
 * const schemaEnum = toValidObject({ type: RoleEnum, allow: "optional" });
 * schemaEnum.parse("admin");     // "admin"
 * schemaEnum.parse("superuser"); // null (invalid value -> fallback)
 * schemaEnum.parse(null);        // null (replaced with fallback, since null not allowed)
 * schemaEnum.parse(undefined);   // undefined
 *
 * @example
 * // With preserve: false
 * const schemaReplace = toValidObject({ type: z.object({}), allow: "nullish", fallback: {}, preserve: false });
 * schemaReplace.parse(null);      // {} (null allowed, but replaced with fallback)
 * schemaReplace.parse(undefined); // {} (undefined allowed, but replaced with fallback)
 * schemaReplace.parse("oops");    // {} (invalid, replaced with fallback)
 */
declare function toValidObject<T extends z.ZodObject | z.ZodEnum = z.ZodObject, K = null>(type: T, options: Omit<ToValidObjectOptions<T, K>, "type"> & {
    allow: "none";
}): z.ZodPipe<z.ZodTransform, T | (K extends never[] ? T : K extends null | undefined ? T : z.ZodType<K>)>;
declare function toValidObject<T extends z.ZodObject | z.ZodEnum = z.ZodObject, K = null>(options: ToValidObjectOptions<T, K> & {
    allow: "none";
}): z.ZodPipe<z.ZodTransform, T | (K extends never[] ? T : K extends null | undefined ? T : z.ZodType<K>)>;
declare function toValidObject<T extends z.ZodObject | z.ZodEnum = z.ZodObject, K = null>(type: T, options: Omit<ToValidObjectOptions<T, K>, "type"> & {
    preserve: false;
}): z.ZodPipe<z.ZodTransform, T | z.ZodType<K>>;
declare function toValidObject<T extends z.ZodObject | z.ZodEnum = z.ZodObject, K = null>(options: ToValidObjectOptions<T, K> & {
    preserve: false;
}): z.ZodPipe<z.ZodTransform, T | z.ZodType<K>>;
declare function toValidObject<T extends z.ZodObject | z.ZodEnum = z.ZodObject, K = null>(type: T, options: Omit<ToValidObjectOptions<T, K>, "type"> & {
    allow: "optional";
}): z.ZodPipe<z.ZodTransform, z.ZodOptional<z.ZodUnion<[T, z.ZodCustom<K, K>]>>>;
declare function toValidObject<T extends z.ZodObject | z.ZodEnum = z.ZodObject, K = null>(options: ToValidObjectOptions<T, K> & {
    allow: "optional";
}): z.ZodPipe<z.ZodTransform, z.ZodOptional<z.ZodUnion<[T, z.ZodCustom<K, K>]>>>;
declare function toValidObject<T extends z.ZodObject | z.ZodEnum = z.ZodObject, K = null>(type: T, options: Omit<ToValidObjectOptions<T, K>, "type"> & {
    allow: "nullable";
}): z.ZodPipe<z.ZodTransform, z.ZodNullable<z.ZodUnion<[T, z.ZodCustom<K, K>]>>>;
declare function toValidObject<T extends z.ZodObject | z.ZodEnum = z.ZodObject, K = null>(options: ToValidObjectOptions<T, K> & {
    allow: "nullable";
}): z.ZodPipe<z.ZodTransform, z.ZodNullable<z.ZodUnion<[T, z.ZodCustom<K, K>]>>>;
declare function toValidObject<T extends z.ZodObject | z.ZodEnum = z.ZodObject, K = null>(type: T, options?: Omit<ToValidObjectOptions<T, K>, "type">): z.ZodPipe<z.ZodTransform, z.ZodOptional<z.ZodNullable<z.ZodUnion<[T, z.ZodCustom<K, K>]>>>>;
declare function toValidObject<T extends z.ZodObject | z.ZodEnum = z.ZodObject, K = null>(options?: ToValidObjectOptions<T, K>): z.ZodPipe<z.ZodTransform, z.ZodOptional<z.ZodNullable<z.ZodUnion<[T, z.ZodCustom<K, K>]>>>>;

export { toValidArray, toValidBoolean, toValidISO, toValidNumber, toValidObject, toValidString };