@hy_ong/zod-kit 0.0.5 → 0.1.0

package/dist/index.d.ts

@@ -1,17 +1,50 @@
-import { ZodBoolean, ZodNullable, ZodString, ZodNumber } from 'zod';
+import { ZodBoolean, ZodNullable, ZodString, ZodType, ZodNumber } from 'zod';
+import dayjs from 'dayjs';
 
 type Locale = "zh-TW" | "en";
 declare const setLocale: (locale: Locale) => void;
 declare const getLocale: () => Locale;
 
+/**
+ * @fileoverview Boolean validator for Zod Kit
+ *
+ * Provides flexible boolean validation with support for various truthy/falsy values,
+ * strict mode validation, and comprehensive transformation options.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
+
+/**
+ * Type definition for boolean validation error messages
+ *
+ * @interface BooleanMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [shouldBeTrue] - Message when value should be true but isn't
+ * @property {string} [shouldBeFalse] - Message when value should be false but isn't
+ * @property {string} [invalid] - Message when value is not a valid boolean
+ */
 type BooleanMessages = {
     required?: string;
     shouldBeTrue?: string;
     shouldBeFalse?: string;
     invalid?: string;
 };
+/**
+ * Configuration options for boolean validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface BooleanOptions
+ * @property {boolean | null} [defaultValue] - Default value when input is empty
+ * @property {boolean} [shouldBe] - Specific boolean value that must be matched
+ * @property {unknown[]} [truthyValues] - Array of values that should be treated as true
+ * @property {unknown[]} [falsyValues] - Array of values that should be treated as false
+ * @property {boolean} [strict=false] - If true, only accepts actual boolean values
+ * @property {Function} [transform] - Custom transformation function for boolean values
+ * @property {Record<Locale, BooleanMessages>} [i18n] - Custom error messages for different locales
+ */
 type BooleanOptions<IsRequired extends boolean = true> = {
-    required?: IsRequired;
     defaultValue?: IsRequired extends true ? boolean : boolean | null;
     shouldBe?: boolean;
     truthyValues?: unknown[];
@@ -20,9 +53,103 @@ type BooleanOptions<IsRequired extends boolean = true> = {
     transform?: (value: boolean) => boolean;
     i18n?: Record<Locale, BooleanMessages>;
 };
+/**
+ * Type alias for boolean validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef BooleanSchema
+ * @description Returns ZodBoolean if required, ZodNullable<ZodBoolean> if optional
+ */
 type BooleanSchema<IsRequired extends boolean> = IsRequired extends true ? ZodBoolean : ZodNullable<ZodBoolean>;
-declare function boolean<IsRequired extends boolean = true>(options?: BooleanOptions<IsRequired>): BooleanSchema<IsRequired>;
+/**
+ * Creates a Zod schema for boolean validation with flexible value interpretation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {IsRequired} [required=false] - Whether the field is required
+ * @param {Omit<BooleanOptions<IsRequired>, 'required'>} [options] - Configuration options for boolean validation
+ * @returns {BooleanSchema<IsRequired>} Zod schema for boolean validation
+ *
+ * @description
+ * Creates a flexible boolean validator that can interpret various values as true/false,
+ * supports strict mode for type safety, and provides comprehensive transformation options.
+ *
+ * Features:
+ * - Flexible truthy/falsy value interpretation
+ * - Strict mode for type safety
+ * - Custom transformation functions
+ * - Specific boolean value requirements
+ * - Comprehensive internationalization
+ * - Default value support
+ *
+ * @example
+ * ```typescript
+ * // Basic boolean validation (optional by default)
+ * const basicSchema = boolean()
+ * basicSchema.parse(true) // ✓ Valid
+ * basicSchema.parse("true") // ✓ Valid (converted to true)
+ * basicSchema.parse(null) // ✓ Valid (optional)
+ *
+ * // Required boolean
+ * const requiredSchema = boolean(true)
+ * requiredSchema.parse(true) // ✓ Valid
+ * requiredSchema.parse(null) // ✗ Invalid (required)
+ *
+ * // Strict mode (only actual booleans)
+ * const strictSchema = boolean(false, { strict: true })
+ * strictSchema.parse(true) // ✓ Valid
+ * strictSchema.parse("true") // ✗ Invalid
+ *
+ * // Must be true
+ * const mustBeTrueSchema = boolean(true, { shouldBe: true })
+ * mustBeTrueSchema.parse(true) // ✓ Valid
+ * mustBeTrueSchema.parse(false) // ✗ Invalid
+ *
+ * // Custom truthy/falsy values
+ * const customSchema = boolean(false, {
+ *   truthyValues: ["yes", "on", 1],
+ *   falsyValues: ["no", "off", 0]
+ * })
+ * customSchema.parse("yes") // ✓ Valid (converted to true)
+ *
+ * // Optional with default
+ * const optionalSchema = boolean(false, { defaultValue: false })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link BooleanOptions} for all available configuration options
+ */
+declare function boolean<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<BooleanOptions<IsRequired>, 'required'>): BooleanSchema<IsRequired>;
+
+/**
+ * @fileoverview Date validator for Zod Kit
+ *
+ * Provides comprehensive date validation with format support, range validation,
+ * temporal constraints, and weekday/weekend filtering using dayjs library.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
 
+/**
+ * Type definition for date validation error messages
+ *
+ * @interface DateMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when date is invalid
+ * @property {string} [format] - Message when date doesn't match expected format
+ * @property {string} [min] - Message when date is before minimum allowed
+ * @property {string} [max] - Message when date is after maximum allowed
+ * @property {string} [includes] - Message when date string doesn't contain required text
+ * @property {string} [excludes] - Message when date string contains forbidden text
+ * @property {string} [past] - Message when date must be in the past
+ * @property {string} [future] - Message when date must be in the future
+ * @property {string} [today] - Message when date must be today
+ * @property {string} [notToday] - Message when date must not be today
+ * @property {string} [weekday] - Message when date must be a weekday
+ * @property {string} [notWeekday] - Message when date must not be a weekday
+ * @property {string} [weekend] - Message when date must be a weekend
+ * @property {string} [notWeekend] - Message when date must not be a weekend
+ */
 type DateMessages = {
     required?: string;
     invalid?: string;
@@ -40,8 +167,29 @@ type DateMessages = {
     weekend?: string;
     notWeekend?: string;
 };
+/**
+ * Configuration options for date validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface DateOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {string} [min] - Minimum allowed date (in same format as specified)
+ * @property {string} [max] - Maximum allowed date (in same format as specified)
+ * @property {string} [format="YYYY-MM-DD"] - Date format for parsing and validation
+ * @property {string} [includes] - String that must be included in the date
+ * @property {string | string[]} [excludes] - String(s) that must not be included
+ * @property {boolean} [mustBePast] - Whether date must be in the past
+ * @property {boolean} [mustBeFuture] - Whether date must be in the future
+ * @property {boolean} [mustBeToday] - Whether date must be today
+ * @property {boolean} [mustNotBeToday] - Whether date must not be today
+ * @property {boolean} [weekdaysOnly] - Whether date must be a weekday (Monday-Friday)
+ * @property {boolean} [weekendsOnly] - Whether date must be a weekend (Saturday-Sunday)
+ * @property {Function} [transform] - Custom transformation function for date strings
+ * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, DateMessages>} [i18n] - Custom error messages for different locales
+ */
 type DateOptions<IsRequired extends boolean = true> = {
-    required?: IsRequired;
     min?: string;
     max?: string;
     format?: string;
@@ -57,9 +205,411 @@ type DateOptions<IsRequired extends boolean = true> = {
     defaultValue?: IsRequired extends true ? string : string | null;
     i18n?: Record<Locale, DateMessages>;
 };
+/**
+ * Type alias for date validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef DateSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
 type DateSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>;
-declare function date<IsRequired extends boolean = true>(options?: DateOptions<IsRequired>): DateSchema<IsRequired>;
+/**
+ * Creates a Zod schema for date validation with temporal constraints
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {IsRequired} [required=false] - Whether the field is required
+ * @param {Omit<ValidatorOptions<IsRequired>, 'required'>} [options] - Configuration options for validation
+ * @returns {DateSchema<IsRequired>} Zod schema for date validation
+ *
+ * @description
+ * Creates a comprehensive date validator with format support, range validation,
+ * temporal constraints, and weekday/weekend filtering using dayjs library.
+ *
+ * Features:
+ * - Flexible date format parsing (default: YYYY-MM-DD)
+ * - Range validation (min/max dates)
+ * - Temporal validation (past/future/today)
+ * - Weekday/weekend filtering
+ * - Content inclusion/exclusion
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ * - Strict date parsing with format validation
+ *
+ * @example
+ * ```typescript
+ * // Basic date validation (YYYY-MM-DD)
+ * const basicSchema = date()
+ * basicSchema.parse("2024-03-15") // ✓ Valid
+ * basicSchema.parse(null) // ✓ Valid (optional)
+ *
+ * // Required validation
+ * const requiredSchema = parse("2024-03-15") // ✓ Valid
+(true)
+ * requiredSchema.parse(null) // ✗ Invalid (required)
+ *
+ * basicSchema.parse("2024-13-01") // ✗ Invalid (month 13)
+ *
+ * // Custom format
+ * const customFormatSchema = date(false, { format: "DD/MM/YYYY" })
+ * customFormatSchema.parse("15/03/2024") // ✓ Valid
+ * customFormatSchema.parse("2024-03-15") // ✗ Invalid (wrong format)
+ *
+ * // Date range validation
+ * const rangeSchema = date(false, {
+ *   min: "2024-01-01",
+ *   max: "2024-12-31"
+ * })
+ * rangeSchema.parse("2024-06-15") // ✓ Valid
+ * rangeSchema.parse("2023-12-31") // ✗ Invalid (before min)
+ *
+ * // Future dates only
+ * const futureSchema = date(false, { mustBeFuture: true })
+ * futureSchema.parse("2030-01-01") // ✓ Valid (assuming current date < 2030)
+ * futureSchema.parse("2020-01-01") // ✗ Invalid (past date)
+ *
+ * // Weekdays only (Monday-Friday)
+ * const weekdaySchema = date(false, { weekdaysOnly: true })
+ * weekdaySchema.parse("2024-03-15") // ✓ Valid (if Friday)
+ * weekdaySchema.parse("2024-03-16") // ✗ Invalid (if Saturday)
+ *
+ * // Business date validation
+ * const businessSchema = date(false, {
+ *   format: "YYYY-MM-DD",
+ *   mustBeFuture: true,
+ *   weekdaysOnly: true
+ * })
+ *
+ * // Optional with default
+ * const optionalSchema = date(false, {
+ *   defaultValue: "2024-01-01"
+ * })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link DateOptions} for all available configuration options
+ */
+declare function date<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<DateOptions<IsRequired>, 'required'>): DateSchema<IsRequired>;
+
+/**
+ * @fileoverview DateTime validator for Zod Kit
+ *
+ * Provides comprehensive datetime validation with support for multiple formats,
+ * timezone handling, range validation, and internationalization.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
+
+/**
+ * Type definition for datetime validation error messages
+ *
+ * @interface DateTimeMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when datetime format is invalid
+ * @property {string} [format] - Message when datetime doesn't match expected format
+ * @property {string} [min] - Message when datetime is before minimum allowed
+ * @property {string} [max] - Message when datetime is after maximum allowed
+ * @property {string} [includes] - Message when datetime doesn't include required string
+ * @property {string} [excludes] - Message when datetime contains excluded string
+ * @property {string} [past] - Message when datetime must be in the past
+ * @property {string} [future] - Message when datetime must be in the future
+ * @property {string} [today] - Message when datetime must be today
+ * @property {string} [notToday] - Message when datetime must not be today
+ * @property {string} [weekday] - Message when datetime must be a weekday
+ * @property {string} [weekend] - Message when datetime must be a weekend
+ * @property {string} [hour] - Message when hour is outside allowed range
+ * @property {string} [minute] - Message when minute doesn't match step requirement
+ * @property {string} [customRegex] - Message when custom regex validation fails
+ * @property {string} [notInWhitelist] - Message when value is not in whitelist
+ */
+type DateTimeMessages = {
+    required?: string;
+    invalid?: string;
+    format?: string;
+    min?: string;
+    max?: string;
+    includes?: string;
+    excludes?: string;
+    past?: string;
+    future?: string;
+    today?: string;
+    notToday?: string;
+    weekday?: string;
+    weekend?: string;
+    hour?: string;
+    minute?: string;
+    customRegex?: string;
+    notInWhitelist?: string;
+};
+/**
+ * Supported datetime formats for validation
+ *
+ * @typedef {string} DateTimeFormat
+ *
+ * Standard formats:
+ * - YYYY-MM-DD HH:mm: ISO-style date with 24-hour time (2024-03-15 14:30)
+ * - YYYY-MM-DD HH:mm:ss: ISO-style date with seconds (2024-03-15 14:30:45)
+ * - YYYY-MM-DD hh:mm A: ISO-style date with 12-hour time (2024-03-15 02:30 PM)
+ * - YYYY-MM-DD hh:mm:ss A: ISO-style date with 12-hour time and seconds (2024-03-15 02:30:45 PM)
+ *
+ * Regional formats:
+ * - DD/MM/YYYY HH:mm: European format (15/03/2024 14:30)
+ * - DD/MM/YYYY HH:mm:ss: European format with seconds (15/03/2024 14:30:45)
+ * - DD/MM/YYYY hh:mm A: European format with 12-hour time (15/03/2024 02:30 PM)
+ * - MM/DD/YYYY HH:mm: US format (03/15/2024 14:30)
+ * - MM/DD/YYYY hh:mm A: US format with 12-hour time (03/15/2024 02:30 PM)
+ * - YYYY/MM/DD HH:mm: Alternative slash format (2024/03/15 14:30)
+ * - DD-MM-YYYY HH:mm: European dash format (15-03-2024 14:30)
+ * - MM-DD-YYYY HH:mm: US dash format (03-15-2024 14:30)
+ *
+ * Special formats:
+ * - ISO: ISO 8601 format (2024-03-15T14:30:45.000Z)
+ * - RFC: RFC 2822 format (Fri, 15 Mar 2024 14:30:45 GMT)
+ * - UNIX: Unix timestamp (1710508245)
+ */
+type DateTimeFormat = "YYYY-MM-DD HH:mm" | "YYYY-MM-DD HH:mm:ss" | "YYYY-MM-DD hh:mm A" | "YYYY-MM-DD hh:mm:ss A" | "DD/MM/YYYY HH:mm" | "DD/MM/YYYY HH:mm:ss" | "DD/MM/YYYY hh:mm A" | "MM/DD/YYYY HH:mm" | "MM/DD/YYYY hh:mm A" | "YYYY/MM/DD HH:mm" | "DD-MM-YYYY HH:mm" | "MM-DD-YYYY HH:mm" | "ISO" | "RFC" | "UNIX";
+/**
+ * Configuration options for datetime validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface DateTimeOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {DateTimeFormat} [format="YYYY-MM-DD HH:mm"] - Expected datetime format
+ * @property {string | Date} [min] - Minimum allowed datetime
+ * @property {string | Date} [max] - Maximum allowed datetime
+ * @property {number} [minHour] - Minimum allowed hour (0-23)
+ * @property {number} [maxHour] - Maximum allowed hour (0-23)
+ * @property {number[]} [allowedHours] - Specific hours that are allowed
+ * @property {number} [minuteStep] - Required minute intervals (e.g., 15 for :00, :15, :30, :45)
+ * @property {string} [timezone] - Timezone for parsing and validation (e.g., "Asia/Taipei")
+ * @property {string} [includes] - String that must be included in the datetime
+ * @property {string | string[]} [excludes] - String(s) that must not be included
+ * @property {RegExp} [regex] - Custom regex for validation (overrides format validation)
+ * @property {"trim" | "trimStart" | "trimEnd" | "none"} [trimMode="trim"] - Whitespace handling
+ * @property {"upper" | "lower" | "none"} [casing="none"] - Case transformation
+ * @property {boolean} [mustBePast] - Whether datetime must be in the past
+ * @property {boolean} [mustBeFuture] - Whether datetime must be in the future
+ * @property {boolean} [mustBeToday] - Whether datetime must be today
+ * @property {boolean} [mustNotBeToday] - Whether datetime must not be today
+ * @property {boolean} [weekdaysOnly] - Whether datetime must be a weekday (Monday-Friday)
+ * @property {boolean} [weekendsOnly] - Whether datetime must be a weekend (Saturday-Sunday)
+ * @property {string[]} [whitelist] - Specific datetime strings that are always allowed
+ * @property {boolean} [whitelistOnly=false] - If true, only values in whitelist are allowed
+ * @property {Function} [transform] - Custom transformation function applied before validation
+ * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, DateTimeMessages>} [i18n] - Custom error messages for different locales
+ */
+type DateTimeOptions<IsRequired extends boolean = true> = {
+    format?: DateTimeFormat;
+    min?: string | Date;
+    max?: string | Date;
+    minHour?: number;
+    maxHour?: number;
+    allowedHours?: number[];
+    minuteStep?: number;
+    timezone?: string;
+    includes?: string;
+    excludes?: string | string[];
+    regex?: RegExp;
+    trimMode?: "trim" | "trimStart" | "trimEnd" | "none";
+    casing?: "upper" | "lower" | "none";
+    mustBePast?: boolean;
+    mustBeFuture?: boolean;
+    mustBeToday?: boolean;
+    mustNotBeToday?: boolean;
+    weekdaysOnly?: boolean;
+    weekendsOnly?: boolean;
+    whitelist?: string[];
+    whitelistOnly?: boolean;
+    transform?: (value: string) => string;
+    defaultValue?: IsRequired extends true ? string : string | null;
+    i18n?: Record<Locale, DateTimeMessages>;
+};
+/**
+ * Type alias for datetime validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef DateTimeSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
+type DateTimeSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>;
+/**
+ * Regular expression patterns for datetime format validation
+ *
+ * @constant {Record<DateTimeFormat, RegExp>} DATETIME_PATTERNS
+ * @description Maps each supported datetime format to its corresponding regex pattern
+ *
+ * Pattern explanations:
+ * - YYYY-MM-DD HH:mm: 4-digit year, 2-digit month, 2-digit day, 24-hour time
+ * - ISO: ISO 8601 format with optional milliseconds and timezone
+ * - RFC: RFC 2822 format with day name, date, time, and timezone
+ * - UNIX: 10-digit Unix timestamp
+ */
+declare const DATETIME_PATTERNS: Record<DateTimeFormat, RegExp>;
+/**
+ * Validates if a datetime string matches the specified format pattern
+ *
+ * @param {string} value - The datetime string to validate
+ * @param {DateTimeFormat} format - The expected datetime format
+ * @returns {boolean} True if the datetime is valid for the given format
+ *
+ * @description
+ * Performs both regex pattern matching and actual datetime parsing validation.
+ * Returns false if either the pattern doesn't match or the parsed datetime is invalid.
+ *
+ * @example
+ * ```typescript
+ * validateDateTimeFormat("2024-03-15 14:30", "YYYY-MM-DD HH:mm") // true
+ * validateDateTimeFormat("2024-03-15 25:30", "YYYY-MM-DD HH:mm") // false (invalid hour)
+ * validateDateTimeFormat("15/03/2024", "YYYY-MM-DD HH:mm") // false (wrong format)
+ * ```
+ */
+declare const validateDateTimeFormat: (value: string, format: DateTimeFormat) => boolean;
+/**
+ * Parses a datetime string into a dayjs object using the specified format
+ *
+ * @param {string} value - The datetime string to parse
+ * @param {DateTimeFormat} format - The expected datetime format
+ * @param {string} [timezone] - Optional timezone for parsing (e.g., "Asia/Taipei")
+ * @returns {dayjs.Dayjs | null} Parsed dayjs object or null if parsing fails
+ *
+ * @description
+ * Handles different datetime formats including ISO, RFC, Unix timestamps, and custom formats.
+ * Uses strict parsing mode for custom formats to ensure accuracy.
+ * Applies timezone conversion if specified.
+ *
+ * @example
+ * ```typescript
+ * parseDateTimeValue("2024-03-15 14:30", "YYYY-MM-DD HH:mm")
+ * // Returns dayjs object for March 15, 2024 at 2:30 PM
+ *
+ * parseDateTimeValue("1710508245", "UNIX")
+ * // Returns dayjs object for the Unix timestamp
+ *
+ * parseDateTimeValue("2024-03-15T14:30:45.000Z", "ISO")
+ * // Returns dayjs object for the ISO datetime
+ * ```
+ *
+ * @throws {Error} Returns null if parsing fails or datetime is invalid
+ */
+declare const parseDateTimeValue: (value: string, format: DateTimeFormat, timezone?: string) => dayjs.Dayjs | null;
+/**
+ * Normalizes a datetime string to the specified format
+ *
+ * @param {string} value - The datetime string to normalize
+ * @param {DateTimeFormat} format - The target datetime format
+ * @param {string} [timezone] - Optional timezone for formatting
+ * @returns {string | null} Normalized datetime string or null if parsing fails
+ *
+ * @description
+ * Parses the input datetime and formats it according to the specified format.
+ * Handles special formats like ISO, RFC, and Unix timestamps appropriately.
+ * Returns null if the input datetime cannot be parsed.
+ *
+ * @example
+ * ```typescript
+ * normalizeDateTimeValue("2024-3-15 2:30 PM", "YYYY-MM-DD HH:mm")
+ * // Returns "2024-03-15 14:30"
+ *
+ * normalizeDateTimeValue("1710508245", "ISO")
+ * // Returns "2024-03-15T14:30:45.000Z"
+ * ```
+ */
+declare const normalizeDateTimeValue: (value: string, format: DateTimeFormat, timezone?: string) => string | null;
+/**
+ * Creates a Zod schema for datetime validation with comprehensive options
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {IsRequired} [required=false] - Whether the field is required
+ * @param {Omit<ValidatorOptions<IsRequired>, 'required'>} [options] - Configuration options for validation
+ * @returns {DateTimeSchema<IsRequired>} Zod schema for datetime validation
+ *
+ * @description
+ * Creates a comprehensive datetime validator that supports multiple formats, timezone handling,
+ * range validation, temporal constraints, and extensive customization options.
+ *
+ * Features:
+ * - Multiple datetime formats (ISO, RFC, Unix, regional formats)
+ * - Timezone support and conversion
+ * - Range validation (min/max datetime)
+ * - Hour and minute constraints
+ * - Temporal validation (past/future/today)
+ * - Weekday/weekend validation
+ * - Whitelist/blacklist support
+ * - Custom regex patterns
+ * - String transformation and case handling
+ * - Comprehensive internationalization
+ *
+ * @example
+ * ```typescript
+ * // Basic datetime validation
+ * const basicSchema = datetime() // optional by default
+ * basicSchema.parse("2024-03-15 14:30") // ✓ Valid
+ * basicSchema.parse(null) // ✓ Valid (optional)
+ *
+ * // Required validation
+ * const requiredSchema = parse("2024-03-15 14:30") // ✓ Valid
+(true)
+ * requiredSchema.parse(null) // ✗ Invalid (required)
+ *
+ *
+ * // Business hours validation
+ * const businessHours = datetime({
+ *   format: "YYYY-MM-DD HH:mm",
+ *   minHour: 9,
+ *   maxHour: 17,
+ *   weekdaysOnly: true
+ * })
+ *
+ * // Timezone-aware validation
+ * const timezoneSchema = datetime(false, {
+ *   timezone: "Asia/Taipei",
+ *   mustBeFuture: true
+ * })
+ *
+ * // Multiple format support
+ * const flexibleSchema = datetime(false, {
+ *   format: "DD/MM/YYYY HH:mm"
+ * })
+ * flexibleSchema.parse("15/03/2024 14:30") // ✓ Valid
+ *
+ * // Optional with default
+ * const optionalSchema = datetime(false, {
+ *   defaultValue: "2024-01-01 00:00"
+ * })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link DateTimeOptions} for all available configuration options
+ * @see {@link DateTimeFormat} for supported datetime formats
+ */
+declare function datetime<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<DateTimeOptions<IsRequired>, 'required'>): DateTimeSchema<IsRequired>;
 
+/**
+ * @fileoverview Email validator for Zod Kit
+ *
+ * Provides comprehensive email validation with domain filtering, business email
+ * validation, disposable email detection, and extensive customization options.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
+
+/**
+ * Type definition for email validation error messages
+ *
+ * @interface EmailMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when email format is invalid
+ * @property {string} [minLength] - Message when email is too short
+ * @property {string} [maxLength] - Message when email is too long
+ * @property {string} [includes] - Message when email doesn't contain required string
+ * @property {string} [domain] - Message when email domain is not allowed
+ * @property {string} [domainBlacklist] - Message when email domain is blacklisted
+ * @property {string} [businessOnly] - Message when free email providers are not allowed
+ * @property {string} [noDisposable] - Message when disposable email addresses are not allowed
+ */
 type EmailMessages = {
     required?: string;
     invalid?: string;
@@ -71,8 +621,27 @@ type EmailMessages = {
     businessOnly?: string;
     noDisposable?: string;
 };
+/**
+ * Configuration options for email validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface EmailOptions
+ * @property {string | string[]} [domain] - Allowed domain(s) for email addresses
+ * @property {string[]} [domainBlacklist] - Domains that are not allowed
+ * @property {number} [minLength] - Minimum length of email address
+ * @property {number} [maxLength] - Maximum length of email address
+ * @property {string} [includes] - String that must be included in the email
+ * @property {string | string[]} [excludes] - String(s) that must not be included
+ * @property {boolean} [allowSubdomains=true] - Whether to allow subdomains in domain validation
+ * @property {boolean} [businessOnly=false] - If true, reject common free email providers
+ * @property {boolean} [noDisposable=false] - If true, reject disposable email addresses
+ * @property {boolean} [lowercase=true] - Whether to convert email to lowercase
+ * @property {Function} [transform] - Custom transformation function for email strings
+ * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, EmailMessages>} [i18n] - Custom error messages for different locales
+ */
 type EmailOptions<IsRequired extends boolean = true> = {
-    required?: IsRequired;
     domain?: string | string[];
     domainBlacklist?: string[];
     minLength?: number;
@@ -87,9 +656,288 @@ type EmailOptions<IsRequired extends boolean = true> = {
     defaultValue?: IsRequired extends true ? string : string | null;
     i18n?: Record<Locale, EmailMessages>;
 };
+/**
+ * Type alias for email validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef EmailSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
 type EmailSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>;
-declare function email<IsRequired extends boolean = true>(options?: EmailOptions<IsRequired>): EmailSchema<IsRequired>;
+/**
+ * Creates a Zod schema for email validation with comprehensive filtering options
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {IsRequired} [required=false] - Whether the field is required
+ * @param {Omit<EmailOptions<IsRequired>, 'required'>} [options] - Configuration options for email validation
+ * @returns {EmailSchema<IsRequired>} Zod schema for email validation
+ *
+ * @description
+ * Creates a comprehensive email validator with domain filtering, business email
+ * validation, disposable email detection, and extensive customization options.
+ *
+ * Features:
+ * - RFC-compliant email format validation
+ * - Domain whitelist/blacklist support
+ * - Business email validation (excludes free providers)
+ * - Disposable email detection
+ * - Subdomain support configuration
+ * - Length validation
+ * - Content inclusion/exclusion
+ * - Automatic lowercase conversion
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ *
+ * @example
+ * ```typescript
+ * // Basic email validation (optional by default)
+ * const basicSchema = email()
+ * basicSchema.parse("user@example.com") // ✓ Valid
+ * basicSchema.parse(null) // ✓ Valid (optional)
+ *
+ * // Required email
+ * const requiredSchema = email(true)
+ * requiredSchema.parse("user@example.com") // ✓ Valid
+ * requiredSchema.parse(null) // ✗ Invalid (required)
+ *
+ * // Domain restriction
+ * const domainSchema = email(false, {
+ *   domain: ["company.com", "organization.org"]
+ * })
+ * domainSchema.parse("user@company.com") // ✓ Valid
+ * domainSchema.parse("user@gmail.com") // ✗ Invalid
+ *
+ * // Business emails only (no free providers)
+ * const businessSchema = email(true, { businessOnly: true })
+ * businessSchema.parse("user@company.com") // ✓ Valid
+ * businessSchema.parse("user@gmail.com") // ✗ Invalid
+ *
+ * // No disposable emails
+ * const noDisposableSchema = email(true, { noDisposable: true })
+ * noDisposableSchema.parse("user@company.com") // ✓ Valid
+ * noDisposableSchema.parse("user@10minutemail.com") // ✗ Invalid
+ *
+ * // Domain blacklist
+ * const blacklistSchema = email(false, {
+ *   domainBlacklist: ["spam.com", "blocked.org"]
+ * })
+ *
+ * // Optional with default
+ * const optionalSchema = email(false, { defaultValue: null })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link EmailOptions} for all available configuration options
+ */
+declare function email<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<EmailOptions<IsRequired>, 'required'>): EmailSchema<IsRequired>;
+
+/**
+ * @fileoverview File validator for Zod Kit
+ *
+ * Provides comprehensive file validation with MIME type filtering, size validation,
+ * extension validation, and extensive customization options.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
+
+/**
+ * Type definition for file validation error messages
+ *
+ * @interface FileMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when file format is invalid
+ * @property {string} [size] - Message when file size exceeds limit
+ * @property {string} [minSize] - Message when file size is too small
+ * @property {string} [maxSize] - Message when file size exceeds maximum
+ * @property {string} [type] - Message when file type is not allowed
+ * @property {string} [extension] - Message when file extension is not allowed
+ * @property {string} [extensionBlacklist] - Message when file extension is blacklisted
+ * @property {string} [name] - Message when file name doesn't match pattern
+ * @property {string} [nameBlacklist] - Message when file name matches blacklisted pattern
+ * @property {string} [imageOnly] - Message when only image files are allowed
+ * @property {string} [documentOnly] - Message when only document files are allowed
+ * @property {string} [videoOnly] - Message when only video files are allowed
+ * @property {string} [audioOnly] - Message when only audio files are allowed
+ * @property {string} [archiveOnly] - Message when only archive files are allowed
+ */
+type FileMessages = {
+    required?: string;
+    invalid?: string;
+    size?: string;
+    minSize?: string;
+    maxSize?: string;
+    type?: string;
+    extension?: string;
+    extensionBlacklist?: string;
+    name?: string;
+    nameBlacklist?: string;
+    imageOnly?: string;
+    documentOnly?: string;
+    videoOnly?: string;
+    audioOnly?: string;
+    archiveOnly?: string;
+};
+/**
+ * Configuration options for file validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface FileOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {number} [maxSize] - Maximum file size in bytes
+ * @property {number} [minSize] - Minimum file size in bytes
+ * @property {string | string[]} [type] - Allowed MIME type(s)
+ * @property {string[]} [typeBlacklist] - MIME types that are not allowed
+ * @property {string | string[]} [extension] - Allowed file extension(s)
+ * @property {string[]} [extensionBlacklist] - File extensions that are not allowed
+ * @property {RegExp | string} [namePattern] - Pattern that file name must match
+ * @property {RegExp | string | Array<RegExp | string>} [nameBlacklist] - Pattern(s) that file name must not match
+ * @property {boolean} [imageOnly=false] - If true, only allow image files
+ * @property {boolean} [documentOnly=false] - If true, only allow document files
+ * @property {boolean} [videoOnly=false] - If true, only allow video files
+ * @property {boolean} [audioOnly=false] - If true, only allow audio files
+ * @property {boolean} [archiveOnly=false] - If true, only allow archive files
+ * @property {boolean} [caseSensitive=false] - Whether extension matching is case-sensitive
+ * @property {Function} [transform] - Custom transformation function for File objects
+ * @property {File | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, FileMessages>} [i18n] - Custom error messages for different locales
+ */
+type FileOptions<IsRequired extends boolean = true> = {
+    maxSize?: number;
+    minSize?: number;
+    type?: string | string[];
+    typeBlacklist?: string[];
+    extension?: string | string[];
+    extensionBlacklist?: string[];
+    namePattern?: RegExp | string;
+    nameBlacklist?: RegExp | string | Array<RegExp | string>;
+    imageOnly?: boolean;
+    documentOnly?: boolean;
+    videoOnly?: boolean;
+    audioOnly?: boolean;
+    archiveOnly?: boolean;
+    caseSensitive?: boolean;
+    transform?: (value: File) => File;
+    defaultValue?: IsRequired extends true ? File : File | null;
+    i18n?: Record<Locale, FileMessages>;
+};
+/**
+ * Type alias for file validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef FileSchema
+ * @description Returns ZodType<File> if required, ZodNullable<ZodType<File>> if optional
+ */
+type FileSchema<IsRequired extends boolean> = IsRequired extends true ? ZodType<File> : ZodNullable<ZodType<File>>;
+/**
+ * Creates a Zod schema for file validation with comprehensive filtering options
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {IsRequired} [required=false] - Whether the field is required
+ * @param {Omit<ValidatorOptions<IsRequired>, 'required'>} [options] - Configuration options for validation
+ * @returns {FileSchema<IsRequired>} Zod schema for file validation
+ *
+ * @description
+ * Creates a comprehensive file validator with MIME type filtering, size validation,
+ * extension validation, and extensive customization options.
+ *
+ * Features:
+ * - File size validation (min/max)
+ * - MIME type whitelist/blacklist support
+ * - File extension whitelist/blacklist support
+ * - File name pattern validation
+ * - Predefined file category filters (image, document, video, audio, archive)
+ * - Case-sensitive/insensitive extension matching
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ *
+ * @example
+ * ```typescript
+ * // Basic file validation
+ * const basicSchema = file() // optional by default
+ * basicSchema.parse(new File(["content"], "test.txt"))
+ * basicSchema.parse(null) // ✓ Valid (optional)
+ *
+ * // Required validation
+ * const requiredSchema = parse(new File(["content"], "test.txt"))
+(true)
+ * requiredSchema.parse(null) // ✗ Invalid (required)
+ *
+ *
+ * // Size restrictions
+ * const sizeSchema = file(false, {
+ *   maxSize: 1024 * 1024, // 1MB
+ *   minSize: 1024 // 1KB
+ * })
+ *
+ * // Extension restrictions
+ * const imageSchema = file(false, {
+ *   extension: [".jpg", ".png", ".gif"],
+ *   maxSize: 5 * 1024 * 1024 // 5MB
+ * })
+ *
+ * // MIME type restrictions
+ * const documentSchema = file(false, {
+ *   type: ["application/pdf", "application/msword"],
+ *   maxSize: 10 * 1024 * 1024 // 10MB
+ * })
+ *
+ * // Image files only
+ * const imageOnlySchema = file(false, { imageOnly: true })
+ *
+ * // Document files only
+ * const docOnlySchema = file(false, { documentOnly: true })
+ *
+ * // Name pattern validation
+ * const patternSchema = file(false, {
+ *   namePattern: /^[a-zA-Z0-9_-]+\.(pdf|doc|docx)$/,
+ *   maxSize: 5 * 1024 * 1024
+ * })
+ *
+ * // Optional with default
+ * const optionalSchema = file(false, {
+ *   defaultValue: null
+ * })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link FileOptions} for all available configuration options
+ */
+declare function file<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<FileOptions<IsRequired>, 'required'>): FileSchema<IsRequired>;
+
+/**
+ * @fileoverview ID validator for Zod Kit
+ *
+ * Provides comprehensive ID validation with support for multiple ID formats,
+ * auto-detection, custom patterns, and flexible validation options.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
 
+/**
+ * Type definition for ID validation error messages
+ *
+ * @interface IdMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when ID format is invalid
+ * @property {string} [minLength] - Message when ID is too short
+ * @property {string} [maxLength] - Message when ID is too long
+ * @property {string} [numeric] - Message when numeric ID format is invalid
+ * @property {string} [uuid] - Message when UUID format is invalid
+ * @property {string} [objectId] - Message when MongoDB ObjectId format is invalid
+ * @property {string} [nanoid] - Message when Nano ID format is invalid
+ * @property {string} [snowflake] - Message when Snowflake ID format is invalid
+ * @property {string} [cuid] - Message when CUID format is invalid
+ * @property {string} [ulid] - Message when ULID format is invalid
+ * @property {string} [shortid] - Message when ShortId format is invalid
+ * @property {string} [customFormat] - Message when custom regex format is invalid
+ * @property {string} [includes] - Message when ID doesn't contain required string
+ * @property {string} [excludes] - Message when ID contains forbidden string
+ * @property {string} [startsWith] - Message when ID doesn't start with required string
+ * @property {string} [endsWith] - Message when ID doesn't end with required string
+ */
 type IdMessages = {
     required?: string;
     invalid?: string;
@@ -109,9 +957,45 @@ type IdMessages = {
     startsWith?: string;
     endsWith?: string;
 };
+/**
+ * Supported ID types for validation
+ *
+ * @typedef {string} IdType
+ *
+ * Available types:
+ * - numeric: Pure numeric IDs (1, 123, 999999)
+ * - uuid: UUID v4 format (xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx)
+ * - objectId: MongoDB ObjectId (24-character hexadecimal)
+ * - nanoid: Nano ID format (21-character URL-safe)
+ * - snowflake: Twitter Snowflake (19-digit number)
+ * - cuid: CUID format (25-character starting with 'c')
+ * - ulid: ULID format (26-character case-insensitive)
+ * - shortid: ShortId format (7-14 character URL-safe)
+ * - auto: Auto-detect format from the value
+ */
 type IdType = "numeric" | "uuid" | "objectId" | "nanoid" | "snowflake" | "cuid" | "ulid" | "shortid" | "auto";
+/**
+ * Configuration options for ID validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface IdOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {IdType} [type="auto"] - Expected ID type or auto-detection
+ * @property {number} [minLength] - Minimum length of ID
+ * @property {number} [maxLength] - Maximum length of ID
+ * @property {IdType[]} [allowedTypes] - Multiple allowed ID types (overrides type)
+ * @property {RegExp} [customRegex] - Custom regex pattern (overrides type validation)
+ * @property {string} [includes] - String that must be included in ID
+ * @property {string | string[]} [excludes] - String(s) that must not be included
+ * @property {string} [startsWith] - String that ID must start with
+ * @property {string} [endsWith] - String that ID must end with
+ * @property {boolean} [caseSensitive=true] - Whether validation is case-sensitive
+ * @property {Function} [transform] - Custom transformation function for ID
+ * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, IdMessages>} [i18n] - Custom error messages for different locales
+ */
 type IdOptions<IsRequired extends boolean = true> = {
-    required?: IsRequired;
     type?: IdType;
     minLength?: number;
     maxLength?: number;
@@ -126,7 +1010,20 @@ type IdOptions<IsRequired extends boolean = true> = {
     defaultValue?: IsRequired extends true ? string : string | null;
     i18n?: Record<Locale, IdMessages>;
 };
+/**
+ * Type alias for ID validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef IdSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
 type IdSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>;
+/**
+ * Regular expression patterns for different ID formats
+ *
+ * @constant {Record<string, RegExp>} ID_PATTERNS
+ * @description Maps each ID type to its corresponding regex pattern
+ */
 declare const ID_PATTERNS: {
     readonly numeric: RegExp;
     readonly uuid: RegExp;
@@ -137,10 +1034,151 @@ declare const ID_PATTERNS: {
     readonly ulid: RegExp;
     readonly shortid: RegExp;
 };
+/**
+ * Detects the ID type of a given value using pattern matching
+ *
+ * @param {string} value - The ID value to analyze
+ * @returns {IdType | null} The detected ID type or null if no pattern matches
+ *
+ * @description
+ * Attempts to identify the ID type by testing against known patterns.
+ * Patterns are ordered by specificity to avoid false positives.
+ * More specific patterns (UUID, ObjectId) are tested before generic ones (numeric, shortid).
+ *
+ * @example
+ * ```typescript
+ * detectIdType("550e8400-e29b-41d4-a716-446655440000") // "uuid"
+ * detectIdType("507f1f77bcf86cd799439011") // "objectId"
+ * detectIdType("V1StGXR8_Z5jdHi6B-myT") // "nanoid"
+ * detectIdType("123456789") // "numeric"
+ * detectIdType("invalid-id") // null
+ * ```
+ */
 declare const detectIdType: (value: string) => IdType | null;
+/**
+ * Validates if a value matches the specified ID type
+ *
+ * @param {string} value - The ID value to validate
+ * @param {IdType} type - The expected ID type
+ * @returns {boolean} True if the value matches the specified type
+ *
+ * @description
+ * Validates a specific ID type using regex patterns or auto-detection.
+ * For "auto" type, uses detectIdType to check if any known pattern matches.
+ *
+ * @example
+ * ```typescript
+ * validateIdType("123456", "numeric") // true
+ * validateIdType("abc123", "numeric") // false
+ * validateIdType("550e8400-e29b-41d4-a716-446655440000", "uuid") // true
+ * validateIdType("invalid-uuid", "uuid") // false
+ * ```
+ */
 declare const validateIdType: (value: string, type: IdType) => boolean;
-declare function id<IsRequired extends boolean = true>(options?: IdOptions<IsRequired>): IdSchema<IsRequired>;
+/**
+ * Creates a Zod schema for ID validation with comprehensive format support
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {IsRequired} [required=false] - Whether the field is required
+ * @param {Omit<ValidatorOptions<IsRequired>, 'required'>} [options] - Configuration options for validation
+ * @returns {IdSchema<IsRequired>} Zod schema for ID validation
+ *
+ * @description
+ * Creates a comprehensive ID validator with support for multiple ID formats,
+ * auto-detection, custom patterns, and flexible validation options.
+ *
+ * Features:
+ * - Multiple ID format support (UUID, ObjectId, Snowflake, etc.)
+ * - Auto-detection of ID types
+ * - Custom regex pattern support
+ * - Length validation
+ * - Content validation (includes, excludes, startsWith, endsWith)
+ * - Case sensitivity control
+ * - Multiple allowed types
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ *
+ * @example
+ * ```typescript
+ * // Auto-detect ID format
+ * const autoSchema = id()
+ * autoSchema.parse("550e8400-e29b-41d4-a716-446655440000") // ✓ Valid (UUID)
+ * autoSchema.parse("507f1f77bcf86cd799439011") // ✓ Valid (ObjectId)
+ * autoSchema.parse("123456") // ✓ Valid (numeric)
+ *
+ * // Specific ID type
+ * const uuidSchema = id(false, { type: "uuid" })
+ * uuidSchema.parse("550e8400-e29b-41d4-a716-446655440000") // ✓ Valid
+ * uuidSchema.parse("invalid-uuid") // ✗ Invalid
+ *
+ * // Multiple allowed types
+ * const multiSchema = id(false, { allowedTypes: ["uuid", "objectId"] })
+ * multiSchema.parse("550e8400-e29b-41d4-a716-446655440000") // ✓ Valid (UUID)
+ * multiSchema.parse("507f1f77bcf86cd799439011") // ✓ Valid (ObjectId)
+ * multiSchema.parse("123456") // ✗ Invalid (numeric not allowed)
+ *
+ * // Custom regex pattern
+ * const customSchema = id(false, { customRegex: /^CUST_\d{6}$/ })
+ * customSchema.parse("CUST_123456") // ✓ Valid
+ * customSchema.parse("invalid") // ✗ Invalid
+ *
+ * // Content validation
+ * const prefixSchema = id(false, {
+ *   type: "auto",
+ *   startsWith: "user_",
+ *   minLength: 10
+ * })
+ * prefixSchema.parse("user_123456") // ✓ Valid
+ *
+ * // Case insensitive
+ * const caseInsensitiveSchema = id(false, {
+ *   type: "uuid",
+ *   caseSensitive: false
+ * })
+ * caseInsensitiveSchema.parse("550E8400-E29B-41D4-A716-446655440000") // ✓ Valid
+ *
+ * // Optional with default
+ * const optionalSchema = id(false, {
+ *   defaultValue: null
+ * })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link IdOptions} for all available configuration options
+ * @see {@link IdType} for supported ID types
+ * @see {@link detectIdType} for auto-detection logic
+ * @see {@link validateIdType} for type-specific validation
+ */
+declare function id<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<IdOptions<IsRequired>, 'required'>): IdSchema<IsRequired>;
+
+/**
+ * @fileoverview Number validator for Zod Kit
+ *
+ * Provides comprehensive number validation with type constraints, range validation,
+ * precision control, and advanced parsing features including comma-separated numbers.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
 
+/**
+ * Type definition for number validation error messages
+ *
+ * @interface NumberMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when value is not a valid number
+ * @property {string} [integer] - Message when integer is required but float provided
+ * @property {string} [float] - Message when float is required but integer provided
+ * @property {string} [min] - Message when number is below minimum value
+ * @property {string} [max] - Message when number exceeds maximum value
+ * @property {string} [positive] - Message when positive number is required
+ * @property {string} [negative] - Message when negative number is required
+ * @property {string} [nonNegative] - Message when non-negative number is required
+ * @property {string} [nonPositive] - Message when non-positive number is required
+ * @property {string} [multipleOf] - Message when number is not a multiple of specified value
+ * @property {string} [finite] - Message when finite number is required
+ * @property {string} [precision] - Message when number has too many decimal places
+ */
 type NumberMessages = {
     required?: string;
     invalid?: string;
@@ -156,8 +1194,29 @@ type NumberMessages = {
     finite?: string;
     precision?: string;
 };
+/**
+ * Configuration options for number validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface NumberOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {number} [min] - Minimum allowed value
+ * @property {number} [max] - Maximum allowed value
+ * @property {number | null} [defaultValue] - Default value when input is empty
+ * @property {"integer" | "float" | "both"} [type="both"] - Type constraint for the number
+ * @property {boolean} [positive] - Whether number must be positive (> 0)
+ * @property {boolean} [negative] - Whether number must be negative (< 0)
+ * @property {boolean} [nonNegative] - Whether number must be non-negative (>= 0)
+ * @property {boolean} [nonPositive] - Whether number must be non-positive (<= 0)
+ * @property {number} [multipleOf] - Number must be a multiple of this value
+ * @property {number} [precision] - Maximum number of decimal places allowed
+ * @property {boolean} [finite=true] - Whether to reject Infinity and -Infinity
+ * @property {Function} [transform] - Custom transformation function for number values
+ * @property {boolean} [parseCommas=false] - Whether to parse comma-separated numbers (e.g., "1,234")
+ * @property {Record<Locale, NumberMessages>} [i18n] - Custom error messages for different locales
+ */
 type NumberOptions<IsRequired extends boolean = true> = {
-    required?: IsRequired;
     min?: number;
     max?: number;
     defaultValue?: IsRequired extends true ? number : number | null;
@@ -173,9 +1232,116 @@ type NumberOptions<IsRequired extends boolean = true> = {
     parseCommas?: boolean;
     i18n?: Record<Locale, NumberMessages>;
 };
+/**
+ * Type alias for number validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef NumberSchema
+ * @description Returns ZodNumber if required, ZodNullable<ZodNumber> if optional
+ */
 type NumberSchema<IsRequired extends boolean> = IsRequired extends true ? ZodNumber : ZodNullable<ZodNumber>;
-declare function number<IsRequired extends boolean = true>(options?: NumberOptions<IsRequired>): NumberSchema<IsRequired>;
+/**
+ * Creates a Zod schema for number validation with comprehensive constraints
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {NumberOptions<IsRequired>} [options] - Configuration options for number validation
+ * @returns {NumberSchema<IsRequired>} Zod schema for number validation
+ *
+ * @description
+ * Creates a comprehensive number validator with type constraints, range validation,
+ * precision control, and advanced parsing features including comma-separated numbers.
+ *
+ * Features:
+ * - Type constraints (integer, float, or both)
+ * - Range validation (min/max)
+ * - Sign constraints (positive, negative, non-negative, non-positive)
+ * - Multiple-of validation
+ * - Precision control (decimal places)
+ * - Finite number validation
+ * - Comma-separated number parsing
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ *
+ * @example
+ * ```typescript
+ * // Basic number validation (optional by default)
+ * const basicSchema = number()
+ * basicSchema.parse(42) // ✓ Valid
+ * basicSchema.parse("42") // ✓ Valid (converted to number)
+ * basicSchema.parse(null) // ✓ Valid (optional)
+ *
+ * // Required number
+ * const requiredSchema = number(true)
+ * requiredSchema.parse(42) // ✓ Valid
+ * requiredSchema.parse(null) // ✗ Invalid (required)
+ *
+ * // Integer only
+ * const integerSchema = number(false, { type: "integer" })
+ * integerSchema.parse(42) // ✓ Valid
+ * integerSchema.parse(42.5) // ✗ Invalid
+ *
+ * // Range validation
+ * const rangeSchema = number(true, { min: 0, max: 100 })
+ * rangeSchema.parse(50) // ✓ Valid
+ * rangeSchema.parse(150) // ✗ Invalid
+ *
+ * // Positive numbers only
+ * const positiveSchema = number(true, { positive: true })
+ * positiveSchema.parse(5) // ✓ Valid
+ * positiveSchema.parse(-5) // ✗ Invalid
+ *
+ * // Multiple of constraint
+ * const multipleSchema = number(true, { multipleOf: 5 })
+ * multipleSchema.parse(10) // ✓ Valid
+ * multipleSchema.parse(7) // ✗ Invalid
+ *
+ * // Precision control
+ * const precisionSchema = number(true, { precision: 2 })
+ * precisionSchema.parse(3.14) // ✓ Valid
+ * precisionSchema.parse(3.14159) // ✗ Invalid
+ *
+ * // Comma-separated parsing
+ * const commaSchema = number(false, { parseCommas: true })
+ * commaSchema.parse("1,234.56") // ✓ Valid (parsed as 1234.56)
+ *
+ * // Optional with default
+ * const optionalSchema = number(false, { defaultValue: 0 })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link NumberOptions} for all available configuration options
+ */
+declare function number<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<NumberOptions<IsRequired>, 'required'>): NumberSchema<IsRequired>;
 
+/**
+ * @fileoverview Password validator for Zod Kit
+ *
+ * Provides comprehensive password validation with strength analysis, character requirements,
+ * security checks, and protection against common weak passwords.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
+
+/**
+ * Type definition for password validation error messages
+ *
+ * @interface PasswordMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [min] - Message when password is too short
+ * @property {string} [max] - Message when password is too long
+ * @property {string} [uppercase] - Message when uppercase letters are required
+ * @property {string} [lowercase] - Message when lowercase letters are required
+ * @property {string} [digits] - Message when digits are required
+ * @property {string} [special] - Message when special characters are required
+ * @property {string} [noRepeating] - Message when repeating characters are forbidden
+ * @property {string} [noSequential] - Message when sequential characters are forbidden
+ * @property {string} [noCommonWords] - Message when common passwords are forbidden
+ * @property {string} [minStrength] - Message when password strength is insufficient
+ * @property {string} [excludes] - Message when password contains forbidden strings
+ * @property {string} [includes] - Message when password doesn't contain required string
+ * @property {string} [invalid] - Message when password doesn't match custom regex
+ */
 type PasswordMessages = {
     required?: string;
     min?: string;
@@ -192,9 +1358,42 @@ type PasswordMessages = {
     includes?: string;
     invalid?: string;
 };
+/**
+ * Password strength levels used for validation
+ *
+ * @typedef {"weak" | "medium" | "strong" | "very-strong"} PasswordStrength
+ * @description
+ * - weak: Basic passwords with minimal requirements
+ * - medium: Passwords with some character variety
+ * - strong: Passwords with good character variety and length
+ * - very-strong: Passwords with excellent character variety, length, and complexity
+ */
 type PasswordStrength = "weak" | "medium" | "strong" | "very-strong";
+/**
+ * Configuration options for password validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface PasswordOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {number} [min] - Minimum length of password
+ * @property {number} [max] - Maximum length of password
+ * @property {boolean} [uppercase] - Whether uppercase letters are required
+ * @property {boolean} [lowercase] - Whether lowercase letters are required
+ * @property {boolean} [digits] - Whether digits are required
+ * @property {boolean} [special] - Whether special characters are required
+ * @property {boolean} [noRepeating] - Whether to forbid repeating characters (3+ in a row)
+ * @property {boolean} [noSequential] - Whether to forbid sequential characters (abc, 123)
+ * @property {boolean} [noCommonWords] - Whether to forbid common weak passwords
+ * @property {PasswordStrength} [minStrength] - Minimum required password strength
+ * @property {string | string[]} [excludes] - String(s) that must not be included
+ * @property {string} [includes] - String that must be included in password
+ * @property {RegExp} [regex] - Custom regex pattern for validation
+ * @property {Function} [transform] - Custom transformation function for password
+ * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, PasswordMessages>} [i18n] - Custom error messages for different locales
+ */
 type PasswordOptions<IsRequired extends boolean = true> = {
-    required?: IsRequired;
     min?: number;
     max?: number;
     uppercase?: boolean;
@@ -212,9 +1411,120 @@ type PasswordOptions<IsRequired extends boolean = true> = {
     defaultValue?: IsRequired extends true ? string : string | null;
     i18n?: Record<Locale, PasswordMessages>;
 };
+/**
+ * Type alias for password validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef PasswordSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
 type PasswordSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>;
-declare function password<IsRequired extends boolean = true>(options?: PasswordOptions<IsRequired>): PasswordSchema<IsRequired>;
+/**
+ * Creates a Zod schema for password validation with comprehensive security checks
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {IsRequired} [required=false] - Whether the field is required
+ * @param {Omit<ValidatorOptions<IsRequired>, 'required'>} [options] - Configuration options for validation
+ * @returns {PasswordSchema<IsRequired>} Zod schema for password validation
+ *
+ * @description
+ * Creates a comprehensive password validator with strength analysis, character requirements,
+ * security checks, and protection against common weak passwords.
+ *
+ * Features:
+ * - Length validation (min/max)
+ * - Character requirements (uppercase, lowercase, digits, special)
+ * - Security checks (no repeating, no sequential patterns)
+ * - Common password detection
+ * - Strength analysis with configurable minimum levels
+ * - Content inclusion/exclusion
+ * - Custom regex patterns
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ *
+ * @example
+ * ```typescript
+ * // Basic password validation
+ * const basicSchema = password() // optional by default
+ * basicSchema.parse("MyPassword123!") // ✓ Valid
+ * basicSchema.parse(null) // ✓ Valid (optional)
+ *
+ * // Required validation
+ * const requiredSchema = parse("MyPassword123!") // ✓ Valid
+(true)
+ * requiredSchema.parse(null) // ✗ Invalid (required)
+ *
+ *
+ * // Strong password requirements
+ * const strongSchema = password(false, {
+ *   min: 12,
+ *   uppercase: true,
+ *   lowercase: true,
+ *   digits: true,
+ *   special: true,
+ *   minStrength: "strong"
+ * })
+ *
+ * // No common passwords
+ * const secureSchema = password(false, {
+ *   noCommonWords: true,
+ *   noRepeating: true,
+ *   noSequential: true
+ * })
+ * secureSchema.parse("password123") // ✗ Invalid (common password)
+ * secureSchema.parse("aaa123") // ✗ Invalid (repeating characters)
+ * secureSchema.parse("abc123") // ✗ Invalid (sequential characters)
+ *
+ * // Custom requirements
+ * const customSchema = password(false, {
+ *   min: 8,
+ *   includes: "@", // Must contain @
+ *   excludes: ["admin", "user"], // Cannot contain these words
+ *   regex: /^(?=.*[A-Z])(?=.*[a-z])(?=.*\d)/ // Custom pattern
+ * })
+ *
+ * // Minimum strength requirement
+ * const strengthSchema = password(false, { minStrength: "very-strong" })
+ * strengthSchema.parse("weak") // ✗ Invalid (insufficient strength)
+ * strengthSchema.parse("MyVeryStr0ng!P@ssw0rd2024") // ✓ Valid
+ *
+ * // Optional with default
+ * const optionalSchema = password(false, {
+ *   defaultValue: null
+ * })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link PasswordOptions} for all available configuration options
+ * @see {@link PasswordStrength} for strength level definitions
+ * @see {@link calculatePasswordStrength} for strength calculation logic
+ */
+declare function password<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<PasswordOptions<IsRequired>, 'required'>): PasswordSchema<IsRequired>;
+
+/**
+ * @fileoverview Text validator for Zod Kit
+ *
+ * Provides comprehensive text validation with length constraints, content validation,
+ * flexible trimming and casing options, and advanced transformation features.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
 
+/**
+ * Type definition for text validation error messages
+ *
+ * @interface TextMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [notEmpty] - Message when field must not be empty (whitespace-only)
+ * @property {string} [minLength] - Message when text is shorter than minimum length
+ * @property {string} [maxLength] - Message when text exceeds maximum length
+ * @property {string} [startsWith] - Message when text doesn't start with required string
+ * @property {string} [endsWith] - Message when text doesn't end with required string
+ * @property {string} [includes] - Message when text doesn't contain required string
+ * @property {string} [excludes] - Message when text contains forbidden string
+ * @property {string} [invalid] - Message when text doesn't match regex pattern
+ */
 type TextMessages = {
     required?: string;
     notEmpty?: string;
@@ -226,8 +1536,28 @@ type TextMessages = {
     excludes?: string;
     invalid?: string;
 };
+/**
+ * Configuration options for text validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface TextOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {number} [minLength] - Minimum length of text
+ * @property {number} [maxLength] - Maximum length of text
+ * @property {string} [startsWith] - String that text must start with
+ * @property {string} [endsWith] - String that text must end with
+ * @property {string} [includes] - String that must be included in text
+ * @property {string | string[]} [excludes] - String(s) that must not be included
+ * @property {RegExp} [regex] - Regular expression pattern for validation
+ * @property {"trim" | "trimStart" | "trimEnd" | "none"} [trimMode="trim"] - Whitespace handling
+ * @property {"upper" | "lower" | "title" | "none"} [casing="none"] - Case transformation
+ * @property {Function} [transform] - Custom transformation function for text
+ * @property {boolean} [notEmpty] - Whether to reject whitespace-only strings
+ * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, TextMessages>} [i18n] - Custom error messages for different locales
+ */
 type TextOptions<IsRequired extends boolean = true> = {
-    required?: IsRequired;
     minLength?: number;
     maxLength?: number;
     startsWith?: string;
@@ -242,9 +1572,384 @@ type TextOptions<IsRequired extends boolean = true> = {
     defaultValue?: IsRequired extends true ? string : string | null;
     i18n?: Record<Locale, TextMessages>;
 };
+/**
+ * Type alias for text validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef TextSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
 type TextSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>;
-declare function text<IsRequired extends boolean = true>(options?: TextOptions<IsRequired>): TextSchema<IsRequired>;
+/**
+ * Creates a Zod schema for text validation with comprehensive string processing
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {TextOptions<IsRequired>} [options] - Configuration options for text validation
+ * @returns {TextSchema<IsRequired>} Zod schema for text validation
+ *
+ * @description
+ * Creates a comprehensive text validator with length constraints, content validation,
+ * flexible trimming and casing options, and advanced transformation features.
+ *
+ * Features:
+ * - Length validation (min/max)
+ * - Content validation (startsWith, endsWith, includes, excludes)
+ * - Regular expression pattern matching
+ * - Flexible trimming options (trim, trimStart, trimEnd, none)
+ * - Case transformation (upper, lower, title, none)
+ * - Empty string vs whitespace-only validation
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ *
+ * @example
+ * ```typescript
+ * // Basic text validation (optional by default)
+ * const basicSchema = text()
+ * basicSchema.parse("Hello World") // ✓ Valid
+ * basicSchema.parse(null) // ✓ Valid (optional)
+ *
+ * // Required text
+ * const requiredSchema = text(true)
+ * requiredSchema.parse("Hello") // ✓ Valid
+ * requiredSchema.parse(null) // ✗ Invalid (required)
+ *
+ * // Length constraints
+ * const lengthSchema = text(true, { minLength: 3, maxLength: 50 })
+ * lengthSchema.parse("Hello") // ✓ Valid
+ * lengthSchema.parse("Hi") // ✗ Invalid (too short)
+ *
+ * // Content validation
+ * const contentSchema = text(true, {
+ *   startsWith: "Hello",
+ *   endsWith: "!",
+ *   includes: "World"
+ * })
+ * contentSchema.parse("Hello World!") // ✓ Valid
+ *
+ * // Case transformation
+ * const upperSchema = text(false, { casing: "upper" })
+ * upperSchema.parse("hello") // ✓ Valid (converted to "HELLO")
+ *
+ * // Trim modes
+ * const trimStartSchema = text(false, { trimMode: "trimStart" })
+ * trimStartSchema.parse("  hello  ") // ✓ Valid (result: "hello  ")
+ *
+ * // Regex validation
+ * const regexSchema = text(true, { regex: /^[a-zA-Z]+$/ })
+ * regexSchema.parse("hello") // ✓ Valid
+ * regexSchema.parse("hello123") // ✗ Invalid
+ *
+ * // Not empty (rejects whitespace-only)
+ * const notEmptySchema = text(true, { notEmpty: true })
+ * notEmptySchema.parse("hello") // ✓ Valid
+ * notEmptySchema.parse("   ") // ✗ Invalid
+ *
+ * // Optional with default
+ * const optionalSchema = text(false, { defaultValue: "default text" })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link TextOptions} for all available configuration options
+ */
+declare function text<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<TextOptions<IsRequired>, 'required'>): TextSchema<IsRequired>;
+
+/**
+ * @fileoverview Time validator for Zod Kit
+ *
+ * Provides comprehensive time validation with support for multiple time formats,
+ * hour/minute constraints, and advanced time-based validation options.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
+
+/**
+ * Type definition for time validation error messages
+ *
+ * @interface TimeMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when time format is invalid
+ * @property {string} [format] - Message when time doesn't match expected format
+ * @property {string} [min] - Message when time is before minimum allowed
+ * @property {string} [max] - Message when time is after maximum allowed
+ * @property {string} [hour] - Message when hour is outside allowed range
+ * @property {string} [minute] - Message when minute doesn't match step requirement
+ * @property {string} [second] - Message when second doesn't match step requirement
+ * @property {string} [includes] - Message when time doesn't contain required string
+ * @property {string} [excludes] - Message when time contains forbidden string
+ * @property {string} [customRegex] - Message when custom regex validation fails
+ * @property {string} [notInWhitelist] - Message when value is not in whitelist
+ */
+type TimeMessages = {
+    required?: string;
+    invalid?: string;
+    format?: string;
+    min?: string;
+    max?: string;
+    hour?: string;
+    minute?: string;
+    second?: string;
+    includes?: string;
+    excludes?: string;
+    customRegex?: string;
+    notInWhitelist?: string;
+};
+/**
+ * Supported time formats for validation
+ *
+ * @typedef {string} TimeFormat
+ *
+ * Available formats:
+ * - HH:mm: 24-hour format with leading zeros (14:30, 09:30)
+ * - HH:mm:ss: 24-hour format with seconds (14:30:45, 09:30:15)
+ * - hh:mm A: 12-hour format with AM/PM (02:30 PM, 09:30 AM)
+ * - hh:mm:ss A: 12-hour format with seconds and AM/PM (02:30:45 PM)
+ * - H:mm: 24-hour format without leading zeros (14:30, 9:30)
+ * - h:mm A: 12-hour format without leading zeros (2:30 PM, 9:30 AM)
+ */
+type TimeFormat = "HH:mm" | "HH:mm:ss" | "hh:mm A" | "hh:mm:ss A" | "H:mm" | "h:mm A";
+/**
+ * Configuration options for time validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface TimeOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {TimeFormat} [format="HH:mm"] - Expected time format
+ * @property {string} [min] - Minimum allowed time (e.g., "09:00")
+ * @property {string} [max] - Maximum allowed time (e.g., "17:00")
+ * @property {number} [minHour] - Minimum allowed hour (0-23)
+ * @property {number} [maxHour] - Maximum allowed hour (0-23)
+ * @property {number[]} [allowedHours] - Specific hours that are allowed
+ * @property {number} [minuteStep] - Required minute intervals (e.g., 15 for :00, :15, :30, :45)
+ * @property {number} [secondStep] - Required second intervals
+ * @property {string} [includes] - String that must be included in the time
+ * @property {string | string[]} [excludes] - String(s) that must not be included
+ * @property {RegExp} [regex] - Custom regex for validation (overrides format validation)
+ * @property {"trim" | "trimStart" | "trimEnd" | "none"} [trimMode="trim"] - Whitespace handling
+ * @property {"upper" | "lower" | "none"} [casing="none"] - Case transformation
+ * @property {string[]} [whitelist] - Specific time strings that are always allowed
+ * @property {boolean} [whitelistOnly=false] - If true, only values in whitelist are allowed
+ * @property {Function} [transform] - Custom transformation function applied before validation
+ * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, TimeMessages>} [i18n] - Custom error messages for different locales
+ */
+type TimeOptions<IsRequired extends boolean = true> = {
+    format?: TimeFormat;
+    min?: string;
+    max?: string;
+    minHour?: number;
+    maxHour?: number;
+    allowedHours?: number[];
+    minuteStep?: number;
+    secondStep?: number;
+    includes?: string;
+    excludes?: string | string[];
+    regex?: RegExp;
+    trimMode?: "trim" | "trimStart" | "trimEnd" | "none";
+    casing?: "upper" | "lower" | "none";
+    whitelist?: string[];
+    whitelistOnly?: boolean;
+    transform?: (value: string) => string;
+    defaultValue?: IsRequired extends true ? string : string | null;
+    i18n?: Record<Locale, TimeMessages>;
+};
+/**
+ * Type alias for time validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef TimeSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
+type TimeSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>;
+/**
+ * Regular expression patterns for time format validation
+ *
+ * @constant {Record<TimeFormat, RegExp>} TIME_PATTERNS
+ * @description Maps each supported time format to its corresponding regex pattern
+ */
+declare const TIME_PATTERNS: Record<TimeFormat, RegExp>;
+/**
+ * Parses a time string to minutes since midnight for comparison
+ *
+ * @param {string} timeStr - The time string to parse
+ * @param {TimeFormat} format - The expected time format
+ * @returns {number | null} Minutes since midnight (0-1439) or null if parsing fails
+ *
+ * @description
+ * Converts time strings to minutes since midnight for easy comparison and validation.
+ * Handles both 12-hour and 24-hour formats with proper AM/PM conversion.
+ *
+ * @example
+ * ```typescript
+ * parseTimeToMinutes("14:30", "HH:mm") // 870 (14*60 + 30)
+ * parseTimeToMinutes("2:30 PM", "h:mm A") // 870 (14*60 + 30)
+ * parseTimeToMinutes("12:00 AM", "hh:mm A") // 0 (midnight)
+ * parseTimeToMinutes("12:00 PM", "hh:mm A") // 720 (noon)
+ * ```
+ */
+declare const parseTimeToMinutes: (timeStr: string, format: TimeFormat) => number | null;
+/**
+ * Validates if a time string matches the specified format pattern
+ *
+ * @param {string} value - The time string to validate
+ * @param {TimeFormat} format - The expected time format
+ * @returns {boolean} True if the time matches the format pattern
+ *
+ * @description
+ * Performs regex pattern matching to validate time format.
+ * Does not validate actual time values (e.g., 25:00 would pass pattern but fail logic).
+ *
+ * @example
+ * ```typescript
+ * validateTimeFormat("14:30", "HH:mm") // true
+ * validateTimeFormat("2:30 PM", "h:mm A") // true
+ * validateTimeFormat("25:00", "HH:mm") // true (pattern matches)
+ * validateTimeFormat("14:30", "h:mm A") // false (wrong format)
+ * ```
+ */
+declare const validateTimeFormat: (value: string, format: TimeFormat) => boolean;
+/**
+ * Normalizes time to 24-hour format for internal processing
+ *
+ * @param {string} timeStr - The time string to normalize
+ * @param {TimeFormat} format - The current time format
+ * @returns {string | null} Normalized time string or null if parsing fails
+ *
+ * @description
+ * Converts time strings to a standardized 24-hour format for consistent processing.
+ * Handles AM/PM conversion and leading zero normalization.
+ *
+ * @example
+ * ```typescript
+ * normalizeTime("2:30 PM", "h:mm A") // "14:30"
+ * normalizeTime("12:00 AM", "hh:mm A") // "00:00"
+ * normalizeTime("9:30", "H:mm") // "09:30"
+ * normalizeTime("14:30:45", "HH:mm:ss") // "14:30:45"
+ * ```
+ */
+declare const normalizeTime: (timeStr: string, format: TimeFormat) => string | null;
+/**
+ * Creates a Zod schema for time validation with comprehensive options
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {IsRequired} [required=false] - Whether the field is required
+ * @param {Omit<ValidatorOptions<IsRequired>, 'required'>} [options] - Configuration options for validation
+ * @returns {TimeSchema<IsRequired>} Zod schema for time validation
+ *
+ * @description
+ * Creates a comprehensive time validator that supports multiple time formats,
+ * hour/minute constraints, step validation, and extensive customization options.
+ *
+ * Features:
+ * - Multiple time formats (24-hour, 12-hour, with/without seconds)
+ * - Time range validation (min/max)
+ * - Hour and minute constraints
+ * - Step validation (e.g., 15-minute intervals)
+ * - Whitelist/blacklist support
+ * - Custom regex patterns
+ * - String transformation and case handling
+ * - Comprehensive internationalization
+ *
+ * @example
+ * ```typescript
+ * // Basic time validation (24-hour format)
+ * const basicSchema = time()
+ * basicSchema.parse("14:30") // ✓ Valid
+ * basicSchema.parse(null) // ✓ Valid (optional)
+ *
+ * // Required validation
+ * const requiredSchema = parse("14:30") // ✓ Valid
+(true)
+ * requiredSchema.parse(null) // ✗ Invalid (required)
+ *
+ * basicSchema.parse("2:30 PM") // ✗ Invalid (wrong format)
+ *
+ * // 12-hour format with AM/PM
+ * const ampmSchema = time(false, { format: "hh:mm A" })
+ * ampmSchema.parse("02:30 PM") // ✓ Valid
+ * ampmSchema.parse("14:30") // ✗ Invalid (wrong format)
+ *
+ * // Business hours validation
+ * const businessHours = time({
+ *   format: "HH:mm",
+ *   minHour: 9,
+ *   maxHour: 17,
+ *   minuteStep: 15 // Only :00, :15, :30, :45
+ * })
+ * businessHours.parse("09:15") // ✓ Valid
+ * businessHours.parse("18:00") // ✗ Invalid (after maxHour)
+ * businessHours.parse("09:05") // ✗ Invalid (not 15-minute step)
+ *
+ * // Time range validation
+ * const timeRangeSchema = time(false, {
+ *   min: "09:00",
+ *   max: "17:00"
+ * })
+ * timeRangeSchema.parse("12:30") // ✓ Valid
+ * timeRangeSchema.parse("08:00") // ✗ Invalid (before min)
+ *
+ * // Allowed hours only
+ * const specificHours = time({
+ *   allowedHours: [9, 12, 15, 18]
+ * })
+ * specificHours.parse("12:30") // ✓ Valid
+ * specificHours.parse("11:30") // ✗ Invalid (hour not allowed)
+ *
+ * // Whitelist specific times
+ * const whitelistSchema = time(false, {
+ *   whitelist: ["09:00", "12:00", "17:00"],
+ *   whitelistOnly: true
+ * })
+ * whitelistSchema.parse("12:00") // ✓ Valid (in whitelist)
+ * whitelistSchema.parse("13:00") // ✗ Invalid (not in whitelist)
+ *
+ * // Optional with default
+ * const optionalSchema = time(false, {
+ *   defaultValue: "09:00"
+ * })
+ * optionalSchema.parse("") // ✓ Valid (returns "09:00")
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link TimeOptions} for all available configuration options
+ * @see {@link TimeFormat} for supported time formats
+ */
+declare function time<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<TimeOptions<IsRequired>, 'required'>): TimeSchema<IsRequired>;
+
+/**
+ * @fileoverview URL validator for Zod Kit
+ *
+ * Provides comprehensive URL validation with protocol filtering, domain control,
+ * port validation, path constraints, and localhost handling.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
 
+/**
+ * Type definition for URL validation error messages
+ *
+ * @interface UrlMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when URL format is invalid
+ * @property {string} [min] - Message when URL is too short
+ * @property {string} [max] - Message when URL is too long
+ * @property {string} [includes] - Message when URL doesn't contain required string
+ * @property {string} [excludes] - Message when URL contains forbidden string
+ * @property {string} [protocol] - Message when protocol is not allowed
+ * @property {string} [domain] - Message when domain is not allowed
+ * @property {string} [domainBlacklist] - Message when domain is blacklisted
+ * @property {string} [port] - Message when port is not allowed
+ * @property {string} [pathStartsWith] - Message when path doesn't start with required string
+ * @property {string} [pathEndsWith] - Message when path doesn't end with required string
+ * @property {string} [hasQuery] - Message when query parameters are required
+ * @property {string} [noQuery] - Message when query parameters are forbidden
+ * @property {string} [hasFragment] - Message when fragment is required
+ * @property {string} [noFragment] - Message when fragment is forbidden
+ * @property {string} [localhost] - Message when localhost is forbidden
+ * @property {string} [noLocalhost] - Message when localhost is required
+ */
 type UrlMessages = {
     required?: string;
     invalid?: string;
@@ -265,8 +1970,35 @@ type UrlMessages = {
     localhost?: string;
     noLocalhost?: string;
 };
+/**
+ * Configuration options for URL validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface UrlOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {number} [min] - Minimum length of URL
+ * @property {number} [max] - Maximum length of URL
+ * @property {string} [includes] - String that must be included in URL
+ * @property {string | string[]} [excludes] - String(s) that must not be included
+ * @property {string[]} [protocols] - Allowed protocols (e.g., ["https", "http"])
+ * @property {string[]} [allowedDomains] - Domains that are allowed
+ * @property {string[]} [blockedDomains] - Domains that are blocked
+ * @property {number[]} [allowedPorts] - Ports that are allowed
+ * @property {number[]} [blockedPorts] - Ports that are blocked
+ * @property {string} [pathStartsWith] - Path must start with this string
+ * @property {string} [pathEndsWith] - Path must end with this string
+ * @property {boolean} [mustHaveQuery] - Whether URL must have query parameters
+ * @property {boolean} [mustNotHaveQuery] - Whether URL must not have query parameters
+ * @property {boolean} [mustHaveFragment] - Whether URL must have fragment
+ * @property {boolean} [mustNotHaveFragment] - Whether URL must not have fragment
+ * @property {boolean} [allowLocalhost=true] - Whether to allow localhost URLs
+ * @property {boolean} [blockLocalhost] - Whether to explicitly block localhost URLs
+ * @property {Function} [transform] - Custom transformation function for URL strings
+ * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, UrlMessages>} [i18n] - Custom error messages for different locales
+ */
 type UrlOptions<IsRequired extends boolean = true> = {
-    required?: IsRequired;
     min?: number;
     max?: number;
     includes?: string;
@@ -288,89 +2020,1120 @@ type UrlOptions<IsRequired extends boolean = true> = {
     defaultValue?: IsRequired extends true ? string : string | null;
     i18n?: Record<Locale, UrlMessages>;
 };
+/**
+ * Type alias for URL validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef UrlSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
 type UrlSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>;
-declare function url<IsRequired extends boolean = true>(options?: UrlOptions<IsRequired>): UrlSchema<IsRequired>;
+/**
+ * Creates a Zod schema for URL validation with comprehensive constraints
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {IsRequired} [required=false] - Whether the field is required
+ * @param {Omit<ValidatorOptions<IsRequired>, 'required'>} [options] - Configuration options for validation
+ * @returns {UrlSchema<IsRequired>} Zod schema for URL validation
+ *
+ * @description
+ * Creates a comprehensive URL validator with protocol filtering, domain control,
+ * port validation, path constraints, and localhost handling.
+ *
+ * Features:
+ * - RFC-compliant URL format validation
+ * - Protocol whitelist/blacklist (http, https, ftp, etc.)
+ * - Domain whitelist/blacklist with subdomain support
+ * - Port validation and filtering
+ * - Path prefix/suffix validation
+ * - Query parameter requirements
+ * - Fragment requirements
+ * - Localhost detection and control
+ * - Length validation
+ * - Content inclusion/exclusion
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ *
+ * @example
+ * ```typescript
+ * // Basic URL validation
+ * const basicSchema = url() // optional by default
+ * basicSchema.parse("https://example.com") // ✓ Valid
+ * basicSchema.parse(null) // ✓ Valid (optional)
+ *
+ * // Required validation
+ * const requiredSchema = parse("https://example.com") // ✓ Valid
+(true)
+ * requiredSchema.parse(null) // ✗ Invalid (required)
+ *
+ *
+ * // HTTPS only
+ * const httpsSchema = url(false, { protocols: ["https"] })
+ * httpsSchema.parse("https://example.com") // ✓ Valid
+ * httpsSchema.parse("http://example.com") // ✗ Invalid
+ *
+ * // Domain restriction
+ * const domainSchema = url(false, {
+ *   allowedDomains: ["company.com", "trusted.org"]
+ * })
+ * domainSchema.parse("https://app.company.com") // ✓ Valid (subdomain)
+ * domainSchema.parse("https://example.com") // ✗ Invalid
+ *
+ * // Block localhost
+ * const noLocalhostSchema = url(false, { blockLocalhost: true })
+ * noLocalhostSchema.parse("https://example.com") // ✓ Valid
+ * noLocalhostSchema.parse("http://localhost:3000") // ✗ Invalid
+ *
+ * // API endpoints with path requirements
+ * const apiSchema = url(false, {
+ *   pathStartsWith: "/api/",
+ *   mustHaveQuery: true
+ * })
+ * apiSchema.parse("https://api.com/api/users?page=1") // ✓ Valid
+ *
+ * // Port restrictions
+ * const portSchema = url(false, {
+ *   allowedPorts: [80, 443, 8080]
+ * })
+ * portSchema.parse("https://example.com:443") // ✓ Valid
+ * portSchema.parse("https://example.com:3000") // ✗ Invalid
+ *
+ * // Optional with default
+ * const optionalSchema = url(false, {
+ *   defaultValue: null
+ * })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link UrlOptions} for all available configuration options
+ */
+declare function url<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<UrlOptions<IsRequired>, 'required'>): UrlSchema<IsRequired>;
+
+/**
+ * @fileoverview Taiwan Business ID (統一編號) validator for Zod Kit
+ *
+ * Provides validation for Taiwan Business Identification Numbers (統一編號) with
+ * support for both new (2023+) and legacy validation rules.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
 
+/**
+ * Type definition for business ID validation error messages
+ *
+ * @interface BusinessIdMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when business ID format or checksum is invalid
+ */
 type BusinessIdMessages = {
     required?: string;
     invalid?: string;
 };
+/**
+ * Configuration options for Taiwan business ID validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface BusinessIdOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {Function} [transform] - Custom transformation function for business ID
+ * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, BusinessIdMessages>} [i18n] - Custom error messages for different locales
+ */
 type BusinessIdOptions<IsRequired extends boolean = true> = {
-    required?: IsRequired;
     transform?: (value: string) => string;
     defaultValue?: IsRequired extends true ? string : string | null;
     i18n?: Record<Locale, BusinessIdMessages>;
 };
+/**
+ * Type alias for business ID validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef BusinessIdSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
 type BusinessIdSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>;
+/**
+ * Validates Taiwan Business Identification Number (統一編號)
+ *
+ * @param {string} value - The business ID to validate
+ * @returns {boolean} True if the business ID is valid
+ *
+ * @description
+ * Validates Taiwan Business ID using both new (2023+) and legacy validation rules.
+ * The validation includes format checking (8 digits) and checksum verification.
+ *
+ * Validation rules:
+ * 1. Must be exactly 8 digits
+ * 2. Weighted sum calculation using coefficients [1,2,1,2,1,2,4] for first 7 digits
+ * 3. New rules (2023+): Sum + 8th digit must be divisible by 5
+ * 4. Legacy rules: Sum + 8th digit must be divisible by 10
+ * 5. Special case: If 7th digit is 7, try alternative calculation with +1
+ *
+ * @example
+ * ```typescript
+ * validateTaiwanBusinessId("12345675") // true (if valid checksum)
+ * validateTaiwanBusinessId("1234567") // false (not 8 digits)
+ * validateTaiwanBusinessId("abcd1234") // false (not all digits)
+ * ```
+ */
 declare const validateTaiwanBusinessId: (value: string) => boolean;
-declare function businessId<IsRequired extends boolean = true>(options?: BusinessIdOptions<IsRequired>): BusinessIdSchema<IsRequired>;
+/**
+ * Creates a Zod schema for Taiwan Business ID validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {BusinessIdOptions<IsRequired>} [options] - Configuration options for business ID validation
+ * @returns {BusinessIdSchema<IsRequired>} Zod schema for business ID validation
+ *
+ * @description
+ * Creates a comprehensive Taiwan Business ID validator that validates the format
+ * and checksum according to Taiwan government specifications.
+ *
+ * Features:
+ * - 8-digit format validation
+ * - Checksum verification (supports both new 2023+ and legacy rules)
+ * - Automatic trimming and preprocessing
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ * - Optional field support
+ *
+ * @example
+ * ```typescript
+ * // Basic business ID validation
+ * const basicSchema = businessId() // optional by default
+ * basicSchema.parse("12345675") // ✓ Valid (if checksum correct)
+ * basicSchema.parse(null) // ✓ Valid (optional)
+ *
+ * // Required validation
+ * const requiredSchema = parse("12345675") // ✓ Valid (if checksum correct)
+(true)
+ * requiredSchema.parse(null) // ✗ Invalid (required)
+ *
+ * basicSchema.parse("1234567") // ✗ Invalid (not 8 digits)
+ *
+ * // Optional business ID
+ * const optionalSchema = businessId(false)
+ * optionalSchema.parse("") // ✓ Valid (returns null)
+ * optionalSchema.parse("12345675") // ✓ Valid (if checksum correct)
+ *
+ * // With custom transformation
+ * const transformSchema = businessId(false, {
+ *   transform: (value) => value.replace(/[^0-9]/g, '') // Remove non-digits
+ * })
+ * transformSchema.parse("1234-5675") // ✓ Valid (if checksum correct after cleaning)
+ *
+ * // With custom error messages
+ * const customSchema = businessId(false, {
+ *   i18n: {
+ *     en: { invalid: "Please enter a valid Taiwan Business ID" },
+ *     'zh-TW': { invalid: "請輸入有效的統一編號" }
+ *   }
+ * })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link BusinessIdOptions} for all available configuration options
+ * @see {@link validateTaiwanBusinessId} for validation logic details
+ */
+declare function businessId<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<BusinessIdOptions<IsRequired>, 'required'>): BusinessIdSchema<IsRequired>;
 
+/**
+ * @fileoverview Taiwan National ID (身分證/居留證) validator for Zod Kit
+ *
+ * Provides validation for Taiwan National ID cards (身分證) and
+ * Resident Certificates (居留證) with support for both old and new formats.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
+
+/**
+ * Type definition for national ID validation error messages
+ *
+ * @interface NationalIdMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when national ID format or checksum is invalid
+ */
 type NationalIdMessages = {
     required?: string;
     invalid?: string;
 };
+/**
+ * Types of Taiwan national identification documents
+ *
+ * @typedef {"citizen" | "resident" | "both"} NationalIdType
+ *
+ * Available types:
+ * - citizen: National ID card (身分證字號) for Taiwan citizens
+ * - resident: Resident certificate (居留證號) for foreign residents
+ * - both: Accept both citizen and resident IDs
+ */
 type NationalIdType = "citizen" | "resident" | "both";
+/**
+ * Configuration options for Taiwan national ID validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface NationalIdOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {NationalIdType} [type="both"] - Type of ID to accept
+ * @property {boolean} [allowOldResident=true] - Whether to accept old-style resident certificates
+ * @property {Function} [transform] - Custom transformation function for ID
+ * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, NationalIdMessages>} [i18n] - Custom error messages for different locales
+ */
 type NationalIdOptions<IsRequired extends boolean = true> = {
-    required?: IsRequired;
     type?: NationalIdType;
     allowOldResident?: boolean;
     transform?: (value: string) => string;
     defaultValue?: IsRequired extends true ? string : string | null;
     i18n?: Record<Locale, NationalIdMessages>;
 };
+/**
+ * Type alias for national ID validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef NationalIdSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
 type NationalIdSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>;
+/**
+ * Validates Taiwan citizen national ID card (身分證字號)
+ *
+ * @param {string} value - The citizen ID to validate
+ * @returns {boolean} True if the citizen ID is valid
+ *
+ * @description
+ * Validates Taiwan citizen ID format: 1 letter + 1 gender digit (1-2) + 8 digits
+ * Uses checksum algorithm with city code conversion and weighted sum.
+ *
+ * Format: [A-Z][1-2]XXXXXXXX
+ * - First letter: City/county code
+ * - Second digit: Gender (1=male, 2=female)
+ * - Last 8 digits: Serial number + checksum
+ *
+ * @example
+ * ```typescript
+ * validateCitizenId("A123456789") // true/false based on checksum
+ * validateCitizenId("A323456789") // false (invalid gender digit)
+ * ```
+ */
 declare const validateCitizenId: (value: string) => boolean;
+/**
+ * Validates old-style Taiwan resident certificate (舊式居留證號)
+ *
+ * @param {string} value - The old-style resident ID to validate
+ * @returns {boolean} True if the old-style resident ID is valid
+ *
+ * @description
+ * Validates old-style resident ID format: 1 letter + 1 gender letter + 8 digits
+ * Uses checksum algorithm with city code and gender code conversion.
+ *
+ * Format: [A-Z][ABCD]XXXXXXXX
+ * - First letter: City/county code
+ * - Second letter: Gender code (A/C=male, B/D=female)
+ * - Last 8 digits: Serial number + checksum
+ *
+ * @example
+ * ```typescript
+ * validateOldResidentId("AA12345678") // true/false based on checksum
+ * validateOldResidentId("AE12345678") // false (invalid gender letter)
+ * ```
+ */
 declare const validateOldResidentId: (value: string) => boolean;
+/**
+ * Validates new-style Taiwan resident certificate (新式居留證號)
+ *
+ * @param {string} value - The new-style resident ID to validate
+ * @returns {boolean} True if the new-style resident ID is valid
+ *
+ * @description
+ * Validates new-style resident ID format: 1 letter + 1 type digit + 8 digits
+ * Uses the same checksum algorithm as citizen IDs.
+ *
+ * Format: [A-Z][89]XXXXXXXX
+ * - First letter: City/county code
+ * - Second digit: Type indicator (8 or 9)
+ * - Last 8 digits: Serial number + checksum
+ *
+ * @example
+ * ```typescript
+ * validateNewResidentId("A812345678") // true/false based on checksum
+ * validateNewResidentId("A712345678") // false (invalid type digit)
+ * ```
+ */
 declare const validateNewResidentId: (value: string) => boolean;
+/**
+ * Main validation function for Taiwan national IDs
+ *
+ * @param {string} value - The national ID to validate
+ * @param {NationalIdType} [type="both"] - Type of ID to accept
+ * @param {boolean} [allowOldResident=true] - Whether to accept old-style resident certificates
+ * @returns {boolean} True if the national ID is valid
+ *
+ * @description
+ * Validates Taiwan national IDs based on the specified type and options.
+ * Supports citizen IDs, resident certificates (both old and new styles).
+ *
+ * @example
+ * ```typescript
+ * validateTaiwanNationalId("A123456789", "citizen") // Citizen ID only
+ * validateTaiwanNationalId("A812345678", "resident") // Resident ID only
+ * validateTaiwanNationalId("A123456789", "both") // Accept any valid format
+ * validateTaiwanNationalId("AA12345678", "both", false) // Reject old resident format
+ * ```
+ */
 declare const validateTaiwanNationalId: (value: string, type?: NationalIdType, allowOldResident?: boolean) => boolean;
-declare function nationalId<IsRequired extends boolean = true>(options?: NationalIdOptions<IsRequired>): NationalIdSchema<IsRequired>;
+/**
+ * Creates a Zod schema for Taiwan National ID validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {NationalIdOptions<IsRequired>} [options] - Configuration options for national ID validation
+ * @returns {NationalIdSchema<IsRequired>} Zod schema for national ID validation
+ *
+ * @description
+ * Creates a comprehensive Taiwan National ID validator that supports both
+ * citizen IDs and resident certificates with configurable validation rules.
+ *
+ * Features:
+ * - Citizen ID validation (身分證字號)
+ * - Resident certificate validation (居留證號, old and new formats)
+ * - Configurable ID type acceptance
+ * - Automatic case conversion to uppercase
+ * - Checksum verification
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ * - Optional field support
+ *
+ * @example
+ * ```typescript
+ * // Accept any valid Taiwan ID
+ * const anyIdSchema = nationalId()
+ * anyIdSchema.parse("A123456789") // ✓ Valid citizen ID
+ * anyIdSchema.parse("A812345678") // ✓ Valid new resident ID
+ * anyIdSchema.parse("AA12345678") // ✓ Valid old resident ID
+ *
+ * // Citizen IDs only
+ * const citizenSchema = nationalId(false, { type: "citizen" })
+ * citizenSchema.parse("A123456789") // ✓ Valid
+ * citizenSchema.parse("A812345678") // ✗ Invalid (resident ID)
+ *
+ * // Resident IDs only (new format only)
+ * const residentSchema = nationalId(false, {
+ *   type: "resident",
+ *   allowOldResident: false
+ * })
+ * residentSchema.parse("A812345678") // ✓ Valid
+ * residentSchema.parse("AA12345678") // ✗ Invalid (old format)
+ *
+ * // Optional with custom transformation
+ * const optionalSchema = nationalId(false, {
+ *   transform: (value) => value.replace(/[^A-Z0-9]/g, '') // Remove special chars
+ * })
+ *
+ * // With custom error messages
+ * const customSchema = nationalId(false, {
+ *   i18n: {
+ *     en: { invalid: "Please enter a valid Taiwan National ID" },
+ *     'zh-TW': { invalid: "請輸入有效的身分證或居留證號碼" }
+ *   }
+ * })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link NationalIdOptions} for all available configuration options
+ * @see {@link NationalIdType} for supported ID types
+ * @see {@link validateTaiwanNationalId} for validation logic details
+ */
+declare function nationalId<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<NationalIdOptions<IsRequired>, 'required'>): NationalIdSchema<IsRequired>;
+
+/**
+ * @fileoverview Taiwan Mobile Phone Number validator for Zod Kit
+ *
+ * Provides validation for Taiwan mobile phone numbers with support for
+ * all Taiwan mobile network operators and whitelist functionality.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
 
+/**
+ * Type definition for mobile phone validation error messages
+ *
+ * @interface MobileMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when mobile number format is invalid
+ * @property {string} [notInWhitelist] - Message when mobile number is not in whitelist
+ */
 type MobileMessages = {
     required?: string;
     invalid?: string;
     notInWhitelist?: string;
 };
+/**
+ * Configuration options for Taiwan mobile phone validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface MobileOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {string[]} [whitelist] - Array of specific mobile numbers that are always allowed
+ * @property {Function} [transform] - Custom transformation function for mobile number
+ * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, MobileMessages>} [i18n] - Custom error messages for different locales
+ */
 type MobileOptions<IsRequired extends boolean = true> = {
-    required?: IsRequired;
     whitelist?: string[];
     transform?: (value: string) => string;
     defaultValue?: IsRequired extends true ? string : string | null;
     i18n?: Record<Locale, MobileMessages>;
 };
+/**
+ * Type alias for mobile phone validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef MobileSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
 type MobileSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>;
+/**
+ * Validates Taiwan mobile phone number format
+ *
+ * @param {string} value - The mobile phone number to validate
+ * @returns {boolean} True if the mobile number is valid
+ *
+ * @description
+ * Validates Taiwan mobile phone numbers according to the official numbering plan.
+ * Taiwan mobile numbers use the format: 09X-XXXX-XXXX (10 digits total).
+ *
+ * Valid prefixes: 090, 091, 092, 093, 094, 095, 096, 097, 098, 099
+ * - All major Taiwan mobile operators are covered
+ * - Format: 09[0-9] followed by 7 additional digits
+ *
+ * @example
+ * ```typescript
+ * validateTaiwanMobile("0912345678") // true
+ * validateTaiwanMobile("0987654321") // true
+ * validateTaiwanMobile("0812345678") // false (invalid prefix)
+ * validateTaiwanMobile("091234567") // false (too short)
+ * ```
+ */
 declare const validateTaiwanMobile: (value: string) => boolean;
-declare function mobile<IsRequired extends boolean = true>(options?: MobileOptions<IsRequired>): MobileSchema<IsRequired>;
+/**
+ * Creates a Zod schema for Taiwan mobile phone number validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {IsRequired} [required=false] - Whether the field is required
+ * @param {Omit<ValidatorOptions<IsRequired>, 'required'>} [options] - Configuration options for validation
+ * @returns {MobileSchema<IsRequired>} Zod schema for mobile phone validation
+ *
+ * @description
+ * Creates a comprehensive Taiwan mobile phone number validator with support for
+ * all Taiwan mobile network operators and optional whitelist functionality.
+ *
+ * Features:
+ * - Taiwan mobile number format validation (09X-XXXX-XXXX)
+ * - Support for all Taiwan mobile operators (090-099 prefixes)
+ * - Whitelist functionality for specific allowed numbers
+ * - Automatic trimming and preprocessing
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ * - Optional field support
+ *
+ * @example
+ * ```typescript
+ * // Basic mobile number validation
+ * const basicSchema = mobile() // optional by default
+ * basicSchema.parse("0912345678") // ✓ Valid
+ * basicSchema.parse(null) // ✓ Valid (optional)
+ *
+ * // Required validation
+ * const requiredSchema = parse("0912345678") // ✓ Valid
+(true)
+ * requiredSchema.parse(null) // ✗ Invalid (required)
+ *
+ * basicSchema.parse("0987654321") // ✓ Valid
+ * basicSchema.parse("0812345678") // ✗ Invalid (wrong prefix)
+ *
+ * // With whitelist (only specific numbers allowed)
+ * const whitelistSchema = mobile(false, {
+ *   whitelist: ["0912345678", "0987654321"]
+ * })
+ * whitelistSchema.parse("0912345678") // ✓ Valid (in whitelist)
+ * whitelistSchema.parse("0911111111") // ✗ Invalid (not in whitelist)
+ *
+ * // Optional mobile number
+ * const optionalSchema = mobile(false)
+ * optionalSchema.parse("") // ✓ Valid (returns null)
+ * optionalSchema.parse("0912345678") // ✓ Valid
+ *
+ * // With custom transformation
+ * const transformSchema = mobile(false, {
+ *   transform: (value) => value.replace(/[^0-9]/g, '') // Remove non-digits
+ * })
+ * transformSchema.parse("091-234-5678") // ✓ Valid (formatted input)
+ * transformSchema.parse("091 234 5678") // ✓ Valid (spaced input)
+ *
+ * // With custom error messages
+ * const customSchema = mobile(false, {
+ *   i18n: {
+ *     en: { invalid: "Please enter a valid Taiwan mobile number" },
+ *     'zh-TW': { invalid: "請輸入有效的台灣手機號碼" }
+ *   }
+ * })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link MobileOptions} for all available configuration options
+ * @see {@link validateTaiwanMobile} for validation logic details
+ */
+declare function mobile<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<MobileOptions<IsRequired>, 'required'>): MobileSchema<IsRequired>;
 
+/**
+ * @fileoverview Taiwan Postal Code validator for Zod Kit
+ *
+ * Provides comprehensive validation for Taiwan postal codes with support for
+ * 3-digit, 5-digit (legacy), and 6-digit (current) formats based on official
+ * Chunghwa Post specifications.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
+
+/**
+ * Type definition for postal code validation error messages
+ *
+ * @interface PostalCodeMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when postal code format is invalid
+ * @property {string} [invalidFormat] - Message when format doesn't match expected pattern
+ * @property {string} [invalidRange] - Message when postal code is outside valid range
+ * @property {string} [legacy5DigitWarning] - Warning message for 5-digit legacy format
+ * @property {string} [format3Only] - Message when only 3-digit format is allowed
+ * @property {string} [format5Only] - Message when only 5-digit format is allowed
+ * @property {string} [format6Only] - Message when only 6-digit format is allowed
+ */
+type PostalCodeMessages = {
+    required?: string;
+    invalid?: string;
+    invalidFormat?: string;
+    invalidRange?: string;
+    legacy5DigitWarning?: string;
+    format3Only?: string;
+    format5Only?: string;
+    format6Only?: string;
+    invalidSuffix?: string;
+    deprecated5Digit?: string;
+};
+/**
+ * Postal code format types supported in Taiwan
+ *
+ * @typedef {"3" | "5" | "6" | "3+5" | "3+6" | "5+6" | "all"} PostalCodeFormat
+ *
+ * Available formats:
+ * - "3": 3-digit basic postal codes (100-982)
+ * - "5": 5-digit postal codes (3+2 format, legacy)
+ * - "6": 6-digit postal codes (3+3 format, current standard)
+ * - "3+5": Accept both 3-digit and 5-digit formats
+ * - "3+6": Accept both 3-digit and 6-digit formats (recommended)
+ * - "5+6": Accept both 5-digit and 6-digit formats
+ * - "all": Accept all formats (3, 5, and 6 digits)
+ */
+type PostalCodeFormat = "3" | "5" | "6" | "3+5" | "3+6" | "5+6" | "all";
+/**
+ * Configuration options for Taiwan postal code validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface PostalCodeOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {PostalCodeFormat} [format="3+6"] - Which postal code formats to accept
+ * @property {boolean} [strictValidation=true] - Enable strict validation against known postal code ranges
+ * @property {boolean} [allowDashes=true] - Whether to allow dashes in postal codes (e.g., "100-01" or "100-001")
+ * @property {boolean} [warn5Digit=true] - Whether to show warning for 5-digit legacy format
+ * @property {string[]} [allowedPrefixes] - Specific 3-digit prefixes to allow (if strictValidation is true)
+ * @property {string[]} [blockedPrefixes] - Specific 3-digit prefixes to block
+ * @property {Function} [transform] - Custom transformation function for postal codes
+ * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, PostalCodeMessages>} [i18n] - Custom error messages for different locales
+ */
+type PostalCodeOptions<IsRequired extends boolean = true> = {
+    format?: PostalCodeFormat;
+    strictValidation?: boolean;
+    allowDashes?: boolean;
+    warn5Digit?: boolean;
+    allowedPrefixes?: string[];
+    blockedPrefixes?: string[];
+    transform?: (value: string) => string;
+    defaultValue?: IsRequired extends true ? string : string | null;
+    i18n?: Record<Locale, PostalCodeMessages>;
+    strictSuffixValidation?: boolean;
+    deprecate5Digit?: boolean;
+};
+/**
+ * Type alias for postal code validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef PostalCodeSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
+type PostalCodeSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>;
+/**
+ * Valid 3-digit postal code prefixes for Taiwan
+ * Based on official Chunghwa Post data (2024)
+ */
+declare const VALID_3_DIGIT_PREFIXES: string[];
+/**
+ * Validates 3-digit Taiwan postal code
+ *
+ * @param {string} value - The 3-digit postal code to validate
+ * @param {boolean} strictValidation - Whether to validate against known postal code list
+ * @param {string[]} allowedPrefixes - Specific prefixes to allow (overrides strictValidation)
+ * @param {string[]} blockedPrefixes - Specific prefixes to block
+ * @returns {boolean} True if the postal code is valid
+ */
+declare const validate3DigitPostalCode: (value: string, strictValidation?: boolean, allowedPrefixes?: string[], blockedPrefixes?: string[]) => boolean;
+/**
+ * Validates 5-digit Taiwan postal code (legacy format)
+ *
+ * @param {string} value - The 5-digit postal code to validate
+ * @param {boolean} strictValidation - Whether to validate the 3-digit prefix
+ * @param {boolean} strictSuffixValidation - Whether to validate the 2-digit suffix
+ * @param {string[]} allowedPrefixes - Specific prefixes to allow
+ * @param {string[]} blockedPrefixes - Specific prefixes to block
+ * @returns {boolean} True if the postal code is valid
+ */
+declare const validate5DigitPostalCode: (value: string, strictValidation?: boolean, strictSuffixValidation?: boolean, allowedPrefixes?: string[], blockedPrefixes?: string[]) => boolean;
+/**
+ * Validates 6-digit Taiwan postal code (current format)
+ *
+ * @param {string} value - The 6-digit postal code to validate
+ * @param {boolean} strictValidation - Whether to validate the 3-digit prefix
+ * @param {boolean} strictSuffixValidation - Whether to validate the 3-digit suffix
+ * @param {string[]} allowedPrefixes - Specific prefixes to allow
+ * @param {string[]} blockedPrefixes - Specific prefixes to block
+ * @returns {boolean} True if the postal code is valid
+ */
+declare const validate6DigitPostalCode: (value: string, strictValidation?: boolean, strictSuffixValidation?: boolean, allowedPrefixes?: string[], blockedPrefixes?: string[]) => boolean;
+/**
+ * Main validation function for Taiwan postal codes
+ *
+ * @param {string} value - The postal code to validate
+ * @param {PostalCodeFormat} format - Which formats to accept
+ * @param {boolean} strictValidation - Whether to validate against known postal codes
+ * @param {boolean} strictSuffixValidation - Whether to validate suffix ranges
+ * @param {boolean} allowDashes - Whether dashes/spaces are allowed and should be removed
+ * @param {string[]} allowedPrefixes - Specific prefixes to allow
+ * @param {string[]} blockedPrefixes - Specific prefixes to block
+ * @returns {boolean} True if the postal code is valid
+ */
+declare const validateTaiwanPostalCode: (value: string, format?: PostalCodeFormat, strictValidation?: boolean, strictSuffixValidation?: boolean, allowDashes?: boolean, allowedPrefixes?: string[], blockedPrefixes?: string[]) => boolean;
+/**
+ * Creates a Zod schema for Taiwan postal code validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {PostalCodeOptions<IsRequired>} [options] - Configuration options for postal code validation
+ * @returns {PostalCodeSchema<IsRequired>} Zod schema for postal code validation
+ *
+ * @description
+ * Creates a comprehensive Taiwan postal code validator that supports multiple formats
+ * and provides extensive configuration options for different validation scenarios.
+ *
+ * Features:
+ * - 3-digit, 5-digit, and 6-digit postal code format support
+ * - Strict validation against official postal code ranges
+ * - Legacy 5-digit format with optional warnings
+ * - Custom prefix allowlist/blocklist support
+ * - Dash and space handling in postal codes
+ * - Automatic normalization and formatting
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ * - Optional field support
+ *
+ * @example
+ * ```typescript
+ * // Accept 3-digit or 6-digit formats (recommended)
+ * const modernSchema = postalCode()
+ * modernSchema.parse("100")     // ✓ Valid 3-digit
+ * modernSchema.parse("100001")  // ✓ Valid 6-digit
+ * modernSchema.parse("10001")   // ✗ Invalid (5-digit not allowed)
+ *
+ * // Accept all formats
+ * const flexibleSchema = postalCode(false, { format: "all" })
+ * flexibleSchema.parse("100")     // ✓ Valid
+ * flexibleSchema.parse("10001")   // ✓ Valid
+ * flexibleSchema.parse("100001")  // ✓ Valid
+ *
+ * // Only 6-digit format (current standard)
+ * const modernOnlySchema = postalCode(false, { format: "6" })
+ * modernOnlySchema.parse("100001") // ✓ Valid
+ * modernOnlySchema.parse("100")    // ✗ Invalid
+ *
+ * // With dashes allowed
+ * const dashSchema = postalCode(false, { allowDashes: true })
+ * dashSchema.parse("100-001")  // ✓ Valid (normalized to "100001")
+ * dashSchema.parse("100-01")   // ✓ Valid if 5-digit format allowed
+ *
+ * // Specific areas only
+ * const taipeiSchema = postalCode(false, {
+ *   allowedPrefixes: ["100", "103", "104", "105", "106"]
+ * })
+ * taipeiSchema.parse("100001") // ✓ Valid (Taipei area)
+ * taipeiSchema.parse("200001") // ✗ Invalid (not in allowlist)
+ *
+ * // Block specific areas
+ * const blockedSchema = postalCode(false, {
+ *   blockedPrefixes: ["999"] // Block test codes
+ * })
+ *
+ * // With warning for legacy format
+ * const warnSchema = postalCode(false, {
+ *   format: "all",
+ *   warn5Digit: true
+ * })
+ * // Will validate but may show warning for 5-digit codes
+ *
+ * // Optional with custom transformation
+ * const optionalSchema = postalCode(false, {
+ *   transform: (value) => value.replace(/\D/g, '') // Remove non-digits
+ * })
+ *
+ * // Strict suffix validation for real postal codes
+ * const strictSchema = postalCode(false, {
+ *   format: "6",
+ *   strictSuffixValidation: true // Validates suffix range 001-999
+ * })
+ * strictSchema.parse("100001") // ✓ Valid
+ * strictSchema.parse("100000") // ✗ Invalid (suffix 000 not allowed)
+ *
+ * // Deprecate 5-digit codes entirely
+ * const modern2024Schema = postalCode(false, {
+ *   format: "all",
+ *   deprecate5Digit: true // Throws error for any 5-digit code
+ * })
+ * modern2024Schema.parse("100001") // ✓ Valid 6-digit
+ * modern2024Schema.parse("10001")  // ✗ Error: deprecated format
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link PostalCodeOptions} for all available configuration options
+ * @see {@link PostalCodeFormat} for supported formats
+ * @see {@link validateTaiwanPostalCode} for validation logic details
+ */
+declare function postalCode<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<PostalCodeOptions<IsRequired>, 'required'>): PostalCodeSchema<IsRequired>;
+
+/**
+ * @fileoverview Taiwan Landline Telephone Number validator for Zod Kit
+ *
+ * Provides validation for Taiwan landline telephone numbers according to the
+ * official 2024 telecom numbering plan with comprehensive area code support.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
+
+/**
+ * Type definition for telephone validation error messages
+ *
+ * @interface TelMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when telephone number format is invalid
+ * @property {string} [notInWhitelist] - Message when telephone number is not in whitelist
+ */
 type TelMessages = {
     required?: string;
     invalid?: string;
     notInWhitelist?: string;
 };
+/**
+ * Configuration options for Taiwan landline telephone validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface TelOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {string[]} [whitelist] - Array of specific telephone numbers that are always allowed
+ * @property {Function} [transform] - Custom transformation function for telephone number
+ * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, TelMessages>} [i18n] - Custom error messages for different locales
+ */
 type TelOptions<IsRequired extends boolean = true> = {
-    required?: IsRequired;
     whitelist?: string[];
     transform?: (value: string) => string;
     defaultValue?: IsRequired extends true ? string : string | null;
     i18n?: Record<Locale, TelMessages>;
 };
+/**
+ * Type alias for telephone validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef TelSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
 type TelSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>;
+/**
+ * Validates Taiwan landline telephone number format (Official 2024 rules)
+ *
+ * @param {string} value - The telephone number to validate
+ * @returns {boolean} True if the telephone number is valid
+ *
+ * @description
+ * Validates Taiwan landline telephone numbers according to the official 2024
+ * telecom numbering plan. Supports all Taiwan area codes and their specific
+ * number patterns.
+ *
+ * Supported area codes and formats:
+ * - 02: Taipei, New Taipei, Keelung - 8 digits (2&3&5~8+7D)
+ * - 03: Taoyuan, Hsinchu, Yilan, Hualien - 7 digits
+ * - 037: Miaoli - 6 digits (2~9+5D)
+ * - 04: Taichung, Changhua - 7 digits
+ * - 049: Nantou - 7 digits (2~9+6D)
+ * - 05: Yunlin, Chiayi - 7 digits
+ * - 06: Tainan - 7 digits
+ * - 07: Kaohsiung - 7 digits (2~9+6D)
+ * - 08: Pingtung - 7 digits (4&7&8+6D)
+ * - 082: Kinmen - 6 digits (2~5&7~9+5D)
+ * - 0826: Wuqiu - 5 digits (6+4D)
+ * - 0836: Matsu - 5 digits (2~9+4D)
+ * - 089: Taitung - 6 digits (2~9+5D)
+ *
+ * @example
+ * ```typescript
+ * validateTaiwanTel("0223456789") // true (Taipei area)
+ * validateTaiwanTel("0312345678") // true (Taoyuan area)
+ * validateTaiwanTel("037234567") // true (Miaoli area)
+ * validateTaiwanTel("082234567") // true (Kinmen area)
+ * validateTaiwanTel("02-2345-6789") // true (with separators)
+ * validateTaiwanTel("0812345678") // false (invalid for 08 area)
+ * ```
+ */
 declare const validateTaiwanTel: (value: string) => boolean;
-declare function tel<IsRequired extends boolean = true>(options?: TelOptions<IsRequired>): TelSchema<IsRequired>;
+/**
+ * Creates a Zod schema for Taiwan landline telephone number validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {IsRequired} [required=false] - Whether the field is required
+ * @param {Omit<ValidatorOptions<IsRequired>, 'required'>} [options] - Configuration options for validation
+ * @returns {TelSchema<IsRequired>} Zod schema for telephone number validation
+ *
+ * @description
+ * Creates a comprehensive Taiwan landline telephone number validator with support for
+ * all Taiwan area codes according to the official 2024 telecom numbering plan.
+ *
+ * Features:
+ * - Complete Taiwan area code support (02, 03, 037, 04, 049, 05, 06, 07, 08, 082, 0826, 0836, 089)
+ * - Automatic separator handling (hyphens and spaces)
+ * - Area-specific number length and pattern validation
+ * - Whitelist functionality for specific allowed numbers
+ * - Automatic trimming and preprocessing
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ * - Optional field support
+ *
+ * @example
+ * ```typescript
+ * // Basic telephone number validation
+ * const basicSchema = tel() // optional by default
+ * basicSchema.parse("0223456789") // ✓ Valid (Taipei)
+ * basicSchema.parse(null) // ✓ Valid (optional)
+ *
+ * // Required validation
+ * const requiredSchema = parse("0223456789") // ✓ Valid (Taipei)
+(true)
+ * requiredSchema.parse(null) // ✗ Invalid (required)
+ *
+ * basicSchema.parse("0312345678") // ✓ Valid (Taoyuan)
+ * basicSchema.parse("02-2345-6789") // ✓ Valid (with separators)
+ * basicSchema.parse("0812345678") // ✗ Invalid (wrong format for 08)
+ *
+ * // With whitelist (only specific numbers allowed)
+ * const whitelistSchema = tel(false, {
+ *   whitelist: ["0223456789", "0312345678"]
+ * })
+ * whitelistSchema.parse("0223456789") // ✓ Valid (in whitelist)
+ * whitelistSchema.parse("0287654321") // ✗ Invalid (not in whitelist)
+ *
+ * // Optional telephone number
+ * const optionalSchema = tel(false)
+ * optionalSchema.parse("") // ✓ Valid (returns null)
+ * optionalSchema.parse("0223456789") // ✓ Valid
+ *
+ * // With custom transformation (remove separators)
+ * const transformSchema = tel(false, {
+ *   transform: (value) => value.replace(/[^0-9]/g, '') // Keep only digits
+ * })
+ * transformSchema.parse("02-2345-6789") // ✓ Valid (separators removed)
+ * transformSchema.parse("02 2345 6789") // ✓ Valid (spaces removed)
+ *
+ * // With custom error messages
+ * const customSchema = tel(false, {
+ *   i18n: {
+ *     en: { invalid: "Please enter a valid Taiwan landline number" },
+ *     'zh-TW': { invalid: "請輸入有效的台灣市話號碼" }
+ *   }
+ * })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link TelOptions} for all available configuration options
+ * @see {@link validateTaiwanTel} for validation logic details
+ */
+declare function tel<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<TelOptions<IsRequired>, 'required'>): TelSchema<IsRequired>;
+
+/**
+ * @fileoverview Taiwan Fax Number validator for Zod Kit
+ *
+ * Provides validation for Taiwan fax numbers according to the official 2024
+ * telecom numbering plan. Uses the same format as landline telephone numbers.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
 
+/**
+ * Type definition for fax number validation error messages
+ *
+ * @interface FaxMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when fax number format is invalid
+ * @property {string} [notInWhitelist] - Message when fax number is not in whitelist
+ */
 type FaxMessages = {
     required?: string;
     invalid?: string;
     notInWhitelist?: string;
 };
+/**
+ * Configuration options for Taiwan fax number validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface FaxOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {string[]} [whitelist] - Array of specific fax numbers that are always allowed
+ * @property {Function} [transform] - Custom transformation function for fax number
+ * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {Record<Locale, FaxMessages>} [i18n] - Custom error messages for different locales
+ */
 type FaxOptions<IsRequired extends boolean = true> = {
-    required?: IsRequired;
     whitelist?: string[];
     transform?: (value: string) => string;
     defaultValue?: IsRequired extends true ? string : string | null;
     i18n?: Record<Locale, FaxMessages>;
 };
+/**
+ * Type alias for fax number validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef FaxSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
 type FaxSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>;
+/**
+ * Validates Taiwan fax number format (Official 2024 rules - same as landline)
+ *
+ * @param {string} value - The fax number to validate
+ * @returns {boolean} True if the fax number is valid
+ *
+ * @description
+ * Validates Taiwan fax numbers according to the official 2024 telecom numbering plan.
+ * Fax numbers follow the same format as landline telephone numbers in Taiwan.
+ *
+ * Supported area codes and formats (same as landline):
+ * - 02: Taipei, New Taipei, Keelung - 8 digits (2&3&5~8+7D)
+ * - 03: Taoyuan, Hsinchu, Yilan, Hualien - 7 digits
+ * - 037: Miaoli - 6 digits (2~9+5D)
+ * - 04: Taichung, Changhua - 7 digits
+ * - 049: Nantou - 7 digits (2~9+6D)
+ * - 05: Yunlin, Chiayi - 7 digits
+ * - 06: Tainan - 7 digits
+ * - 07: Kaohsiung - 7 digits (2~9+6D)
+ * - 08: Pingtung - 7 digits (4&7&8+6D)
+ * - 082: Kinmen - 6 digits (2~5&7~9+5D)
+ * - 0826: Wuqiu - 5 digits (6+4D)
+ * - 0836: Matsu - 5 digits (2~9+4D)
+ * - 089: Taitung - 6 digits (2~9+5D)
+ *
+ * @example
+ * ```typescript
+ * validateTaiwanFax("0223456789") // true (Taipei area)
+ * validateTaiwanFax("0312345678") // true (Taoyuan area)
+ * validateTaiwanFax("037234567") // true (Miaoli area)
+ * validateTaiwanFax("02-2345-6789") // true (with separators)
+ * validateTaiwanFax("0812345678") // false (invalid for 08 area)
+ * ```
+ */
 declare const validateTaiwanFax: (value: string) => boolean;
-declare function fax<IsRequired extends boolean = true>(options?: FaxOptions<IsRequired>): FaxSchema<IsRequired>;
+/**
+ * Creates a Zod schema for Taiwan fax number validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {IsRequired} [required=false] - Whether the field is required
+ * @param {Omit<ValidatorOptions<IsRequired>, 'required'>} [options] - Configuration options for validation
+ * @returns {FaxSchema<IsRequired>} Zod schema for fax number validation
+ *
+ * @description
+ * Creates a comprehensive Taiwan fax number validator with support for all Taiwan
+ * area codes. Fax numbers follow the same format as landline telephone numbers.
+ *
+ * Features:
+ * - Complete Taiwan area code support (same as landline)
+ * - Automatic separator handling (hyphens and spaces)
+ * - Area-specific number length and pattern validation
+ * - Whitelist functionality for specific allowed numbers
+ * - Automatic trimming and preprocessing
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ * - Optional field support
+ *
+ * @example
+ * ```typescript
+ * // Basic fax number validation
+ * const basicSchema = fax() // optional by default
+ * basicSchema.parse("0223456789") // ✓ Valid (Taipei)
+ * basicSchema.parse(null) // ✓ Valid (optional)
+ *
+ * // Required validation
+ * const requiredSchema = parse("0223456789") // ✓ Valid (Taipei)
+(true)
+ * requiredSchema.parse(null) // ✗ Invalid (required)
+ *
+ * basicSchema.parse("0312345678") // ✓ Valid (Taoyuan)
+ * basicSchema.parse("02-2345-6789") // ✓ Valid (with separators)
+ * basicSchema.parse("0812345678") // ✗ Invalid (wrong format for 08)
+ *
+ * // With whitelist (only specific numbers allowed)
+ * const whitelistSchema = fax(false, {
+ *   whitelist: ["0223456789", "0312345678"]
+ * })
+ * whitelistSchema.parse("0223456789") // ✓ Valid (in whitelist)
+ * whitelistSchema.parse("0287654321") // ✗ Invalid (not in whitelist)
+ *
+ * // Optional fax number
+ * const optionalSchema = fax(false)
+ * optionalSchema.parse("") // ✓ Valid (returns null)
+ * optionalSchema.parse("0223456789") // ✓ Valid
+ *
+ * // With custom transformation
+ * const transformSchema = fax(false, {
+ *   transform: (value) => value.replace(/[^0-9]/g, '') // Keep only digits
+ * })
+ * transformSchema.parse("02-2345-6789") // ✓ Valid (separators removed)
+ *
+ * // With custom error messages
+ * const customSchema = fax(false, {
+ *   i18n: {
+ *     en: { invalid: "Please enter a valid Taiwan fax number" },
+ *     'zh-TW': { invalid: "請輸入有效的台灣傳真號碼" }
+ *   }
+ * })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @see {@link FaxOptions} for all available configuration options
+ * @see {@link validateTaiwanFax} for validation logic details
+ */
+declare function fax<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<FaxOptions<IsRequired>, 'required'>): FaxSchema<IsRequired>;
 
-export { type BooleanMessages, type BooleanOptions, type BooleanSchema, type BusinessIdMessages, type BusinessIdOptions, type BusinessIdSchema, type DateMessages, type DateOptions, type DateSchema, type EmailMessages, type EmailOptions, type EmailSchema, type FaxMessages, type FaxOptions, type FaxSchema, ID_PATTERNS, type IdMessages, type IdOptions, type IdSchema, type IdType, type Locale, type MobileMessages, type MobileOptions, type MobileSchema, type NationalIdMessages, type NationalIdOptions, type NationalIdSchema, type NationalIdType, type NumberMessages, type NumberOptions, type NumberSchema, type PasswordMessages, type PasswordOptions, type PasswordSchema, type PasswordStrength, type TelMessages, type TelOptions, type TelSchema, type TextMessages, type TextOptions, type TextSchema, type UrlMessages, type UrlOptions, type UrlSchema, boolean, businessId, date, detectIdType, email, fax, getLocale, id, mobile, nationalId, number, password, setLocale, tel, text, url, validateCitizenId, validateIdType, validateNewResidentId, validateOldResidentId, validateTaiwanBusinessId, validateTaiwanFax, validateTaiwanMobile, validateTaiwanNationalId, validateTaiwanTel };
+export { type BooleanMessages, type BooleanOptions, type BooleanSchema, type BusinessIdMessages, type BusinessIdOptions, type BusinessIdSchema, DATETIME_PATTERNS, type DateMessages, type DateOptions, type DateSchema, type DateTimeFormat, type DateTimeMessages, type DateTimeOptions, type DateTimeSchema, type EmailMessages, type EmailOptions, type EmailSchema, type FaxMessages, type FaxOptions, type FaxSchema, type FileMessages, type FileOptions, type FileSchema, ID_PATTERNS, type IdMessages, type IdOptions, type IdSchema, type IdType, type Locale, type MobileMessages, type MobileOptions, type MobileSchema, type NationalIdMessages, type NationalIdOptions, type NationalIdSchema, type NationalIdType, type NumberMessages, type NumberOptions, type NumberSchema, type PasswordMessages, type PasswordOptions, type PasswordSchema, type PasswordStrength, type PostalCodeFormat, type PostalCodeMessages, type PostalCodeOptions, type PostalCodeSchema, TIME_PATTERNS, type TelMessages, type TelOptions, type TelSchema, type TextMessages, type TextOptions, type TextSchema, type TimeFormat, type TimeMessages, type TimeOptions, type TimeSchema, type UrlMessages, type UrlOptions, type UrlSchema, VALID_3_DIGIT_PREFIXES, boolean, businessId, date, datetime, detectIdType, email, fax, file, getLocale, id, mobile, nationalId, normalizeDateTimeValue, normalizeTime, number, parseDateTimeValue, parseTimeToMinutes, password, postalCode, setLocale, tel, text, time, url, validate3DigitPostalCode, validate5DigitPostalCode, validate6DigitPostalCode, validateCitizenId, validateDateTimeFormat, validateIdType, validateNewResidentId, validateOldResidentId, validateTaiwanBusinessId, validateTaiwanFax, validateTaiwanMobile, validateTaiwanNationalId, validateTaiwanPostalCode, validateTaiwanTel, validateTimeFormat };