@hy_ong/zod-kit 0.0.6 → 0.1.1

package/dist/index.d.cts

@@ -36,7 +36,6 @@ type BooleanMessages = {
  * @template IsRequired - Whether the field is required (affects return type)
  *
  * @interface BooleanOptions
- * @property {IsRequired} [required=true] - Whether the field is required
  * @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
@@ -46,7 +45,6 @@ type BooleanMessages = {
  * @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[];
@@ -67,7 +65,8 @@ type BooleanSchema<IsRequired extends boolean> = IsRequired extends true ? ZodBo
  * Creates a Zod schema for boolean validation with flexible value interpretation
  *
  * @template IsRequired - Whether the field is required (affects return type)
- * @param {BooleanOptions<IsRequired>} [options] - Configuration options for boolean validation
+ * @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
@@ -84,39 +83,42 @@ type BooleanSchema<IsRequired extends boolean> = IsRequired extends true ? ZodBo
  *
  * @example
  * ```typescript
- * // Basic boolean validation
+ * // 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({ strict: true })
+ * const strictSchema = boolean(false, { strict: true })
  * strictSchema.parse(true) // ✓ Valid
  * strictSchema.parse("true") // ✗ Invalid
  *
  * // Must be true
- * const mustBeTrueSchema = boolean({ shouldBe: true })
+ * const mustBeTrueSchema = boolean(true, { shouldBe: true })
  * mustBeTrueSchema.parse(true) // ✓ Valid
  * mustBeTrueSchema.parse(false) // ✗ Invalid
  *
  * // Custom truthy/falsy values
- * const customSchema = boolean({
+ * 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({
- *   required: false,
- *   defaultValue: false
- * })
+ * 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 = true>(options?: BooleanOptions<IsRequired>): BooleanSchema<IsRequired>;
+declare function boolean<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<BooleanOptions<IsRequired>, 'required'>): BooleanSchema<IsRequired>;
 
 /**
  * @fileoverview Date validator for Zod Kit
@@ -188,7 +190,6 @@ type DateMessages = {
  * @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;
@@ -216,7 +217,8 @@ type DateSchema<IsRequired extends boolean> = IsRequired extends true ? ZodStrin
  * Creates a Zod schema for date validation with temporal constraints
  *
  * @template IsRequired - Whether the field is required (affects return type)
- * @param {DateOptions<IsRequired>} [options] - Configuration options for date validation
+ * @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
@@ -238,15 +240,22 @@ type DateSchema<IsRequired extends boolean> = IsRequired extends true ? ZodStrin
  * // 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({ format: "DD/MM/YYYY" })
+ * 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({
+ * const rangeSchema = date(false, {
  *   min: "2024-01-01",
  *   max: "2024-12-31"
  * })
@@ -254,25 +263,24 @@ type DateSchema<IsRequired extends boolean> = IsRequired extends true ? ZodStrin
  * rangeSchema.parse("2023-12-31") // ✗ Invalid (before min)
  *
  * // Future dates only
- * const futureSchema = date({ mustBeFuture: true })
+ * 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({ weekdaysOnly: true })
+ * 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({
+ * const businessSchema = date(false, {
  *   format: "YYYY-MM-DD",
  *   mustBeFuture: true,
  *   weekdaysOnly: true
  * })
  *
  * // Optional with default
- * const optionalSchema = date({
- *   required: false,
+ * const optionalSchema = date(false, {
  *   defaultValue: "2024-01-01"
  * })
  * ```
@@ -280,7 +288,7 @@ type DateSchema<IsRequired extends boolean> = IsRequired extends true ? ZodStrin
  * @throws {z.ZodError} When validation fails with specific error messages
  * @see {@link DateOptions} for all available configuration options
  */
-declare function date<IsRequired extends boolean = true>(options?: DateOptions<IsRequired>): DateSchema<IsRequired>;
+declare function date<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<DateOptions<IsRequired>, 'required'>): DateSchema<IsRequired>;
 
 /**
  * @fileoverview DateTime validator for Zod Kit
@@ -393,7 +401,6 @@ type DateTimeFormat = "YYYY-MM-DD HH:mm" | "YYYY-MM-DD HH:mm:ss" | "YYYY-MM-DD h
  * @property {Record<Locale, DateTimeMessages>} [i18n] - Custom error messages for different locales
  */
 type DateTimeOptions<IsRequired extends boolean = true> = {
-    required?: IsRequired;
     format?: DateTimeFormat;
     min?: string | Date;
     max?: string | Date;
@@ -514,7 +521,8 @@ declare const normalizeDateTimeValue: (value: string, format: DateTimeFormat, ti
  * Creates a Zod schema for datetime validation with comprehensive options
  *
  * @template IsRequired - Whether the field is required (affects return type)
- * @param {DateTimeOptions<IsRequired>} [options] - Configuration options for datetime validation
+ * @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
@@ -536,8 +544,15 @@ declare const normalizeDateTimeValue: (value: string, format: DateTimeFormat, ti
  * @example
  * ```typescript
  * // Basic datetime validation
- * const basicSchema = datetime()
+ * 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({
@@ -548,20 +563,19 @@ declare const normalizeDateTimeValue: (value: string, format: DateTimeFormat, ti
  * })
  *
  * // Timezone-aware validation
- * const timezoneSchema = datetime({
+ * const timezoneSchema = datetime(false, {
  *   timezone: "Asia/Taipei",
  *   mustBeFuture: true
  * })
  *
  * // Multiple format support
- * const flexibleSchema = datetime({
+ * const flexibleSchema = datetime(false, {
  *   format: "DD/MM/YYYY HH:mm"
  * })
  * flexibleSchema.parse("15/03/2024 14:30") // ✓ Valid
  *
  * // Optional with default
- * const optionalSchema = datetime({
- *   required: false,
+ * const optionalSchema = datetime(false, {
  *   defaultValue: "2024-01-01 00:00"
  * })
  * ```
@@ -570,7 +584,7 @@ declare const normalizeDateTimeValue: (value: string, format: DateTimeFormat, ti
  * @see {@link DateTimeOptions} for all available configuration options
  * @see {@link DateTimeFormat} for supported datetime formats
  */
-declare function datetime<IsRequired extends boolean = true>(options?: DateTimeOptions<IsRequired>): DateTimeSchema<IsRequired>;
+declare function datetime<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<DateTimeOptions<IsRequired>, 'required'>): DateTimeSchema<IsRequired>;
 
 /**
  * @fileoverview Email validator for Zod Kit
@@ -613,7 +627,6 @@ type EmailMessages = {
  * @template IsRequired - Whether the field is required (affects return type)
  *
  * @interface EmailOptions
- * @property {IsRequired} [required=true] - Whether the field is required
  * @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
@@ -629,7 +642,6 @@ type EmailMessages = {
  * @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;
@@ -656,7 +668,8 @@ type EmailSchema<IsRequired extends boolean> = IsRequired extends true ? ZodStri
  * Creates a Zod schema for email validation with comprehensive filtering options
  *
  * @template IsRequired - Whether the field is required (affects return type)
- * @param {EmailOptions<IsRequired>} [options] - Configuration options for email validation
+ * @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
@@ -677,43 +690,46 @@ type EmailSchema<IsRequired extends boolean> = IsRequired extends true ? ZodStri
  *
  * @example
  * ```typescript
- * // Basic email validation
+ * // 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({
+ * 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({ businessOnly: true })
+ * const businessSchema = email(true, { businessOnly: true })
  * businessSchema.parse("user@company.com") // ✓ Valid
  * businessSchema.parse("user@gmail.com") // ✗ Invalid
  *
  * // No disposable emails
- * const noDisposableSchema = email({ noDisposable: true })
+ * const noDisposableSchema = email(true, { noDisposable: true })
  * noDisposableSchema.parse("user@company.com") // ✓ Valid
  * noDisposableSchema.parse("user@10minutemail.com") // ✗ Invalid
  *
  * // Domain blacklist
- * const blacklistSchema = email({
+ * const blacklistSchema = email(false, {
  *   domainBlacklist: ["spam.com", "blocked.org"]
  * })
  *
  * // Optional with default
- * const optionalSchema = email({
- *   required: false,
- *   defaultValue: null
- * })
+ * 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 = true>(options?: EmailOptions<IsRequired>): EmailSchema<IsRequired>;
+declare function email<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<EmailOptions<IsRequired>, 'required'>): EmailSchema<IsRequired>;
 
 /**
  * @fileoverview File validator for Zod Kit
@@ -788,7 +804,6 @@ type FileMessages = {
  * @property {Record<Locale, FileMessages>} [i18n] - Custom error messages for different locales
  */
 type FileOptions<IsRequired extends boolean = true> = {
-    required?: IsRequired;
     maxSize?: number;
     minSize?: number;
     type?: string | string[];
@@ -819,7 +834,8 @@ type FileSchema<IsRequired extends boolean> = IsRequired extends true ? ZodType<
  * Creates a Zod schema for file validation with comprehensive filtering options
  *
  * @template IsRequired - Whether the field is required (affects return type)
- * @param {FileOptions<IsRequired>} [options] - Configuration options for file validation
+ * @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
@@ -839,42 +855,48 @@ type FileSchema<IsRequired extends boolean> = IsRequired extends true ? ZodType<
  * @example
  * ```typescript
  * // Basic file validation
- * const basicSchema = file()
+ * 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({
+ * const sizeSchema = file(false, {
  *   maxSize: 1024 * 1024, // 1MB
  *   minSize: 1024 // 1KB
  * })
  *
  * // Extension restrictions
- * const imageSchema = file({
+ * const imageSchema = file(false, {
  *   extension: [".jpg", ".png", ".gif"],
  *   maxSize: 5 * 1024 * 1024 // 5MB
  * })
  *
  * // MIME type restrictions
- * const documentSchema = file({
+ * const documentSchema = file(false, {
  *   type: ["application/pdf", "application/msword"],
  *   maxSize: 10 * 1024 * 1024 // 10MB
  * })
  *
  * // Image files only
- * const imageOnlySchema = file({ imageOnly: true })
+ * const imageOnlySchema = file(false, { imageOnly: true })
  *
  * // Document files only
- * const docOnlySchema = file({ documentOnly: true })
+ * const docOnlySchema = file(false, { documentOnly: true })
  *
  * // Name pattern validation
- * const patternSchema = file({
+ * const patternSchema = file(false, {
  *   namePattern: /^[a-zA-Z0-9_-]+\.(pdf|doc|docx)$/,
  *   maxSize: 5 * 1024 * 1024
  * })
  *
  * // Optional with default
- * const optionalSchema = file({
- *   required: false,
+ * const optionalSchema = file(false, {
  *   defaultValue: null
  * })
  * ```
@@ -882,7 +904,7 @@ type FileSchema<IsRequired extends boolean> = IsRequired extends true ? ZodType<
  * @throws {z.ZodError} When validation fails with specific error messages
  * @see {@link FileOptions} for all available configuration options
  */
-declare function file<IsRequired extends boolean = true>(options?: FileOptions<IsRequired>): FileSchema<IsRequired>;
+declare function file<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<FileOptions<IsRequired>, 'required'>): FileSchema<IsRequired>;
 
 /**
  * @fileoverview ID validator for Zod Kit
@@ -974,7 +996,6 @@ type IdType = "numeric" | "uuid" | "objectId" | "nanoid" | "snowflake" | "cuid"
  * @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;
@@ -1058,7 +1079,8 @@ declare const validateIdType: (value: string, type: IdType) => boolean;
  * Creates a Zod schema for ID validation with comprehensive format support
  *
  * @template IsRequired - Whether the field is required (affects return type)
- * @param {IdOptions<IsRequired>} [options] - Configuration options for ID validation
+ * @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
@@ -1085,23 +1107,23 @@ declare const validateIdType: (value: string, type: IdType) => boolean;
  * autoSchema.parse("123456") // ✓ Valid (numeric)
  *
  * // Specific ID type
- * const uuidSchema = id({ type: "uuid" })
+ * 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({ allowedTypes: ["uuid", "objectId"] })
+ * 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({ customRegex: /^CUST_\d{6}$/ })
+ * const customSchema = id(false, { customRegex: /^CUST_\d{6}$/ })
  * customSchema.parse("CUST_123456") // ✓ Valid
  * customSchema.parse("invalid") // ✗ Invalid
  *
  * // Content validation
- * const prefixSchema = id({
+ * const prefixSchema = id(false, {
  *   type: "auto",
  *   startsWith: "user_",
  *   minLength: 10
@@ -1109,15 +1131,14 @@ declare const validateIdType: (value: string, type: IdType) => boolean;
  * prefixSchema.parse("user_123456") // ✓ Valid
  *
  * // Case insensitive
- * const caseInsensitiveSchema = id({
+ * const caseInsensitiveSchema = id(false, {
  *   type: "uuid",
  *   caseSensitive: false
  * })
  * caseInsensitiveSchema.parse("550E8400-E29B-41D4-A716-446655440000") // ✓ Valid
  *
  * // Optional with default
- * const optionalSchema = id({
- *   required: false,
+ * const optionalSchema = id(false, {
  *   defaultValue: null
  * })
  * ```
@@ -1128,7 +1149,7 @@ declare const validateIdType: (value: string, type: IdType) => boolean;
  * @see {@link detectIdType} for auto-detection logic
  * @see {@link validateIdType} for type-specific validation
  */
-declare function id<IsRequired extends boolean = true>(options?: IdOptions<IsRequired>): IdSchema<IsRequired>;
+declare function id<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<IdOptions<IsRequired>, 'required'>): IdSchema<IsRequired>;
 
 /**
  * @fileoverview Number validator for Zod Kit
@@ -1196,7 +1217,6 @@ type NumberMessages = {
  * @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;
@@ -1244,51 +1264,54 @@ type NumberSchema<IsRequired extends boolean> = IsRequired extends true ? ZodNum
  *
  * @example
  * ```typescript
- * // Basic number validation
+ * // 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({ type: "integer" })
+ * const integerSchema = number(false, { type: "integer" })
  * integerSchema.parse(42) // ✓ Valid
  * integerSchema.parse(42.5) // ✗ Invalid
  *
  * // Range validation
- * const rangeSchema = number({ min: 0, max: 100 })
+ * const rangeSchema = number(true, { min: 0, max: 100 })
  * rangeSchema.parse(50) // ✓ Valid
  * rangeSchema.parse(150) // ✗ Invalid
  *
  * // Positive numbers only
- * const positiveSchema = number({ positive: true })
+ * const positiveSchema = number(true, { positive: true })
  * positiveSchema.parse(5) // ✓ Valid
  * positiveSchema.parse(-5) // ✗ Invalid
  *
  * // Multiple of constraint
- * const multipleSchema = number({ multipleOf: 5 })
+ * const multipleSchema = number(true, { multipleOf: 5 })
  * multipleSchema.parse(10) // ✓ Valid
  * multipleSchema.parse(7) // ✗ Invalid
  *
  * // Precision control
- * const precisionSchema = number({ precision: 2 })
+ * const precisionSchema = number(true, { precision: 2 })
  * precisionSchema.parse(3.14) // ✓ Valid
  * precisionSchema.parse(3.14159) // ✗ Invalid
  *
  * // Comma-separated parsing
- * const commaSchema = number({ parseCommas: true })
+ * const commaSchema = number(false, { parseCommas: true })
  * commaSchema.parse("1,234.56") // ✓ Valid (parsed as 1234.56)
  *
  * // Optional with default
- * const optionalSchema = number({
- *   required: false,
- *   defaultValue: 0
- * })
+ * 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 = true>(options?: NumberOptions<IsRequired>): NumberSchema<IsRequired>;
+declare function number<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<NumberOptions<IsRequired>, 'required'>): NumberSchema<IsRequired>;
 
 /**
  * @fileoverview Password validator for Zod Kit
@@ -1371,7 +1394,6 @@ type PasswordStrength = "weak" | "medium" | "strong" | "very-strong";
  * @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;
@@ -1401,7 +1423,8 @@ type PasswordSchema<IsRequired extends boolean> = IsRequired extends true ? ZodS
  * Creates a Zod schema for password validation with comprehensive security checks
  *
  * @template IsRequired - Whether the field is required (affects return type)
- * @param {PasswordOptions<IsRequired>} [options] - Configuration options for password validation
+ * @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
@@ -1422,11 +1445,18 @@ type PasswordSchema<IsRequired extends boolean> = IsRequired extends true ? ZodS
  * @example
  * ```typescript
  * // Basic password validation
- * const basicSchema = password()
+ * 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({
+ * const strongSchema = password(false, {
  *   min: 12,
  *   uppercase: true,
  *   lowercase: true,
@@ -1436,7 +1466,7 @@ type PasswordSchema<IsRequired extends boolean> = IsRequired extends true ? ZodS
  * })
  *
  * // No common passwords
- * const secureSchema = password({
+ * const secureSchema = password(false, {
  *   noCommonWords: true,
  *   noRepeating: true,
  *   noSequential: true
@@ -1446,7 +1476,7 @@ type PasswordSchema<IsRequired extends boolean> = IsRequired extends true ? ZodS
  * secureSchema.parse("abc123") // ✗ Invalid (sequential characters)
  *
  * // Custom requirements
- * const customSchema = password({
+ * const customSchema = password(false, {
  *   min: 8,
  *   includes: "@", // Must contain @
  *   excludes: ["admin", "user"], // Cannot contain these words
@@ -1454,13 +1484,12 @@ type PasswordSchema<IsRequired extends boolean> = IsRequired extends true ? ZodS
  * })
  *
  * // Minimum strength requirement
- * const strengthSchema = password({ minStrength: "very-strong" })
+ * 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({
- *   required: false,
+ * const optionalSchema = password(false, {
  *   defaultValue: null
  * })
  * ```
@@ -1470,7 +1499,7 @@ type PasswordSchema<IsRequired extends boolean> = IsRequired extends true ? ZodS
  * @see {@link PasswordStrength} for strength level definitions
  * @see {@link calculatePasswordStrength} for strength calculation logic
  */
-declare function password<IsRequired extends boolean = true>(options?: PasswordOptions<IsRequired>): PasswordSchema<IsRequired>;
+declare function password<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<PasswordOptions<IsRequired>, 'required'>): PasswordSchema<IsRequired>;
 
 /**
  * @fileoverview Text validator for Zod Kit
@@ -1529,7 +1558,6 @@ type TextMessages = {
  * @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;
@@ -1575,17 +1603,23 @@ type TextSchema<IsRequired extends boolean> = IsRequired extends true ? ZodStrin
  *
  * @example
  * ```typescript
- * // Basic text validation
+ * // 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({ minLength: 3, maxLength: 50 })
+ * const lengthSchema = text(true, { minLength: 3, maxLength: 50 })
  * lengthSchema.parse("Hello") // ✓ Valid
  * lengthSchema.parse("Hi") // ✗ Invalid (too short)
  *
  * // Content validation
- * const contentSchema = text({
+ * const contentSchema = text(true, {
  *   startsWith: "Hello",
  *   endsWith: "!",
  *   includes: "World"
@@ -1593,34 +1627,31 @@ type TextSchema<IsRequired extends boolean> = IsRequired extends true ? ZodStrin
  * contentSchema.parse("Hello World!") // ✓ Valid
  *
  * // Case transformation
- * const upperSchema = text({ casing: "upper" })
+ * const upperSchema = text(false, { casing: "upper" })
  * upperSchema.parse("hello") // ✓ Valid (converted to "HELLO")
  *
  * // Trim modes
- * const trimStartSchema = text({ trimMode: "trimStart" })
+ * const trimStartSchema = text(false, { trimMode: "trimStart" })
  * trimStartSchema.parse("  hello  ") // ✓ Valid (result: "hello  ")
  *
  * // Regex validation
- * const regexSchema = text({ regex: /^[a-zA-Z]+$/ })
+ * const regexSchema = text(true, { regex: /^[a-zA-Z]+$/ })
  * regexSchema.parse("hello") // ✓ Valid
  * regexSchema.parse("hello123") // ✗ Invalid
  *
  * // Not empty (rejects whitespace-only)
- * const notEmptySchema = text({ notEmpty: true })
+ * const notEmptySchema = text(true, { notEmpty: true })
  * notEmptySchema.parse("hello") // ✓ Valid
  * notEmptySchema.parse("   ") // ✗ Invalid
  *
  * // Optional with default
- * const optionalSchema = text({
- *   required: false,
- *   defaultValue: "default text"
- * })
+ * 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 = true>(options?: TextOptions<IsRequired>): TextSchema<IsRequired>;
+declare function text<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<TextOptions<IsRequired>, 'required'>): TextSchema<IsRequired>;
 
 /**
  * @fileoverview Time validator for Zod Kit
@@ -1704,7 +1735,6 @@ type TimeFormat = "HH:mm" | "HH:mm:ss" | "hh:mm A" | "hh:mm:ss A" | "H:mm" | "h:
  * @property {Record<Locale, TimeMessages>} [i18n] - Custom error messages for different locales
  */
 type TimeOptions<IsRequired extends boolean = true> = {
-    required?: IsRequired;
     format?: TimeFormat;
     min?: string;
     max?: string;
@@ -1803,7 +1833,8 @@ declare const normalizeTime: (timeStr: string, format: TimeFormat) => string | n
  * Creates a Zod schema for time validation with comprehensive options
  *
  * @template IsRequired - Whether the field is required (affects return type)
- * @param {TimeOptions<IsRequired>} [options] - Configuration options for time validation
+ * @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
@@ -1825,10 +1856,17 @@ declare const normalizeTime: (timeStr: string, format: TimeFormat) => string | n
  * // 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({ format: "hh:mm A" })
+ * const ampmSchema = time(false, { format: "hh:mm A" })
  * ampmSchema.parse("02:30 PM") // ✓ Valid
  * ampmSchema.parse("14:30") // ✗ Invalid (wrong format)
  *
@@ -1844,7 +1882,7 @@ declare const normalizeTime: (timeStr: string, format: TimeFormat) => string | n
  * businessHours.parse("09:05") // ✗ Invalid (not 15-minute step)
  *
  * // Time range validation
- * const timeRangeSchema = time({
+ * const timeRangeSchema = time(false, {
  *   min: "09:00",
  *   max: "17:00"
  * })
@@ -1859,7 +1897,7 @@ declare const normalizeTime: (timeStr: string, format: TimeFormat) => string | n
  * specificHours.parse("11:30") // ✗ Invalid (hour not allowed)
  *
  * // Whitelist specific times
- * const whitelistSchema = time({
+ * const whitelistSchema = time(false, {
  *   whitelist: ["09:00", "12:00", "17:00"],
  *   whitelistOnly: true
  * })
@@ -1867,8 +1905,7 @@ declare const normalizeTime: (timeStr: string, format: TimeFormat) => string | n
  * whitelistSchema.parse("13:00") // ✗ Invalid (not in whitelist)
  *
  * // Optional with default
- * const optionalSchema = time({
- *   required: false,
+ * const optionalSchema = time(false, {
  *   defaultValue: "09:00"
  * })
  * optionalSchema.parse("") // ✓ Valid (returns "09:00")
@@ -1878,7 +1915,7 @@ declare const normalizeTime: (timeStr: string, format: TimeFormat) => string | n
  * @see {@link TimeOptions} for all available configuration options
  * @see {@link TimeFormat} for supported time formats
  */
-declare function time<IsRequired extends boolean = true>(options?: TimeOptions<IsRequired>): TimeSchema<IsRequired>;
+declare function time<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<TimeOptions<IsRequired>, 'required'>): TimeSchema<IsRequired>;
 
 /**
  * @fileoverview URL validator for Zod Kit
@@ -1962,7 +1999,6 @@ type UrlMessages = {
  * @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;
@@ -1996,7 +2032,8 @@ type UrlSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString
  * Creates a Zod schema for URL validation with comprehensive constraints
  *
  * @template IsRequired - Whether the field is required (affects return type)
- * @param {UrlOptions<IsRequired>} [options] - Configuration options for URL validation
+ * @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
@@ -2020,43 +2057,49 @@ type UrlSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString
  * @example
  * ```typescript
  * // Basic URL validation
- * const basicSchema = url()
+ * 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({ protocols: ["https"] })
+ * const httpsSchema = url(false, { protocols: ["https"] })
  * httpsSchema.parse("https://example.com") // ✓ Valid
  * httpsSchema.parse("http://example.com") // ✗ Invalid
  *
  * // Domain restriction
- * const domainSchema = url({
+ * 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({ blockLocalhost: true })
+ * 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({
+ * const apiSchema = url(false, {
  *   pathStartsWith: "/api/",
  *   mustHaveQuery: true
  * })
  * apiSchema.parse("https://api.com/api/users?page=1") // ✓ Valid
  *
  * // Port restrictions
- * const portSchema = url({
+ * 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({
- *   required: false,
+ * const optionalSchema = url(false, {
  *   defaultValue: null
  * })
  * ```
@@ -2064,7 +2107,7 @@ type UrlSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString
  * @throws {z.ZodError} When validation fails with specific error messages
  * @see {@link UrlOptions} for all available configuration options
  */
-declare function url<IsRequired extends boolean = true>(options?: UrlOptions<IsRequired>): UrlSchema<IsRequired>;
+declare function url<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<UrlOptions<IsRequired>, 'required'>): UrlSchema<IsRequired>;
 
 /**
  * @fileoverview Taiwan Business ID (統一編號) validator for Zod Kit
@@ -2099,7 +2142,6 @@ type BusinessIdMessages = {
  * @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>;
@@ -2159,23 +2201,30 @@ declare const validateTaiwanBusinessId: (value: string) => boolean;
  * @example
  * ```typescript
  * // Basic business ID validation
- * const basicSchema = businessId()
+ * 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({ required: false })
+ * const optionalSchema = businessId(false)
  * optionalSchema.parse("") // ✓ Valid (returns null)
  * optionalSchema.parse("12345675") // ✓ Valid (if checksum correct)
  *
  * // With custom transformation
- * const transformSchema = businessId({
+ * 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({
+ * const customSchema = businessId(false, {
  *   i18n: {
  *     en: { invalid: "Please enter a valid Taiwan Business ID" },
  *     'zh-TW': { invalid: "請輸入有效的統一編號" }
@@ -2187,7 +2236,7 @@ declare const validateTaiwanBusinessId: (value: string) => boolean;
  * @see {@link BusinessIdOptions} for all available configuration options
  * @see {@link validateTaiwanBusinessId} for validation logic details
  */
-declare function businessId<IsRequired extends boolean = true>(options?: BusinessIdOptions<IsRequired>): BusinessIdSchema<IsRequired>;
+declare function businessId<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<BusinessIdOptions<IsRequired>, 'required'>): BusinessIdSchema<IsRequired>;
 
 /**
  * @fileoverview Taiwan National ID (身分證/居留證) validator for Zod Kit
@@ -2235,7 +2284,6 @@ type NationalIdType = "citizen" | "resident" | "both";
  * @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;
@@ -2367,12 +2415,12 @@ declare const validateTaiwanNationalId: (value: string, type?: NationalIdType, a
  * anyIdSchema.parse("AA12345678") // ✓ Valid old resident ID
  *
  * // Citizen IDs only
- * const citizenSchema = nationalId({ type: "citizen" })
+ * 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({
+ * const residentSchema = nationalId(false, {
  *   type: "resident",
  *   allowOldResident: false
  * })
@@ -2380,13 +2428,12 @@ declare const validateTaiwanNationalId: (value: string, type?: NationalIdType, a
  * residentSchema.parse("AA12345678") // ✗ Invalid (old format)
  *
  * // Optional with custom transformation
- * const optionalSchema = nationalId({
- *   required: false,
+ * const optionalSchema = nationalId(false, {
  *   transform: (value) => value.replace(/[^A-Z0-9]/g, '') // Remove special chars
  * })
  *
  * // With custom error messages
- * const customSchema = nationalId({
+ * const customSchema = nationalId(false, {
  *   i18n: {
  *     en: { invalid: "Please enter a valid Taiwan National ID" },
  *     'zh-TW': { invalid: "請輸入有效的身分證或居留證號碼" }
@@ -2399,7 +2446,7 @@ declare const validateTaiwanNationalId: (value: string, type?: NationalIdType, a
  * @see {@link NationalIdType} for supported ID types
  * @see {@link validateTaiwanNationalId} for validation logic details
  */
-declare function nationalId<IsRequired extends boolean = true>(options?: NationalIdOptions<IsRequired>): NationalIdSchema<IsRequired>;
+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
@@ -2437,7 +2484,6 @@ type MobileMessages = {
  * @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;
@@ -2478,7 +2524,8 @@ declare const validateTaiwanMobile: (value: string) => boolean;
  * Creates a Zod schema for Taiwan mobile phone number validation
  *
  * @template IsRequired - Whether the field is required (affects return type)
- * @param {MobileOptions<IsRequired>} [options] - Configuration options for mobile validation
+ * @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
@@ -2497,32 +2544,39 @@ declare const validateTaiwanMobile: (value: string) => boolean;
  * @example
  * ```typescript
  * // Basic mobile number validation
- * const basicSchema = mobile()
+ * 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({
+ * 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({ required: false })
+ * const optionalSchema = mobile(false)
  * optionalSchema.parse("") // ✓ Valid (returns null)
  * optionalSchema.parse("0912345678") // ✓ Valid
  *
  * // With custom transformation
- * const transformSchema = mobile({
+ * 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({
+ * const customSchema = mobile(false, {
  *   i18n: {
  *     en: { invalid: "Please enter a valid Taiwan mobile number" },
  *     'zh-TW': { invalid: "請輸入有效的台灣手機號碼" }
@@ -2534,7 +2588,7 @@ declare const validateTaiwanMobile: (value: string) => boolean;
  * @see {@link MobileOptions} for all available configuration options
  * @see {@link validateTaiwanMobile} for validation logic details
  */
-declare function mobile<IsRequired extends boolean = true>(options?: MobileOptions<IsRequired>): MobileSchema<IsRequired>;
+declare function mobile<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<MobileOptions<IsRequired>, 'required'>): MobileSchema<IsRequired>;
 
 /**
  * @fileoverview Taiwan Postal Code validator for Zod Kit
@@ -2605,7 +2659,6 @@ type PostalCodeFormat = "3" | "5" | "6" | "3+5" | "3+6" | "5+6" | "all";
  * @property {Record<Locale, PostalCodeMessages>} [i18n] - Custom error messages for different locales
  */
 type PostalCodeOptions<IsRequired extends boolean = true> = {
-    required?: IsRequired;
     format?: PostalCodeFormat;
     strictValidation?: boolean;
     allowDashes?: boolean;
@@ -2707,48 +2760,47 @@ declare const validateTaiwanPostalCode: (value: string, format?: PostalCodeForma
  * modernSchema.parse("10001")   // ✗ Invalid (5-digit not allowed)
  *
  * // Accept all formats
- * const flexibleSchema = postalCode({ format: "all" })
+ * 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({ format: "6" })
+ * const modernOnlySchema = postalCode(false, { format: "6" })
  * modernOnlySchema.parse("100001") // ✓ Valid
  * modernOnlySchema.parse("100")    // ✗ Invalid
  *
  * // With dashes allowed
- * const dashSchema = postalCode({ allowDashes: true })
+ * 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({
+ * 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({
+ * const blockedSchema = postalCode(false, {
  *   blockedPrefixes: ["999"] // Block test codes
  * })
  *
  * // With warning for legacy format
- * const warnSchema = postalCode({
+ * 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({
- *   required: false,
+ * const optionalSchema = postalCode(false, {
  *   transform: (value) => value.replace(/\D/g, '') // Remove non-digits
  * })
  *
  * // Strict suffix validation for real postal codes
- * const strictSchema = postalCode({
+ * const strictSchema = postalCode(false, {
  *   format: "6",
  *   strictSuffixValidation: true // Validates suffix range 001-999
  * })
@@ -2756,7 +2808,7 @@ declare const validateTaiwanPostalCode: (value: string, format?: PostalCodeForma
  * strictSchema.parse("100000") // ✗ Invalid (suffix 000 not allowed)
  *
  * // Deprecate 5-digit codes entirely
- * const modern2024Schema = postalCode({
+ * const modern2024Schema = postalCode(false, {
  *   format: "all",
  *   deprecate5Digit: true // Throws error for any 5-digit code
  * })
@@ -2769,7 +2821,7 @@ declare const validateTaiwanPostalCode: (value: string, format?: PostalCodeForma
  * @see {@link PostalCodeFormat} for supported formats
  * @see {@link validateTaiwanPostalCode} for validation logic details
  */
-declare function postalCode<IsRequired extends boolean = true>(options?: PostalCodeOptions<IsRequired>): PostalCodeSchema<IsRequired>;
+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
@@ -2807,7 +2859,6 @@ type TelMessages = {
  * @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;
@@ -2862,7 +2913,8 @@ declare const validateTaiwanTel: (value: string) => boolean;
  * Creates a Zod schema for Taiwan landline telephone number validation
  *
  * @template IsRequired - Whether the field is required (affects return type)
- * @param {TelOptions<IsRequired>} [options] - Configuration options for telephone validation
+ * @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
@@ -2882,33 +2934,40 @@ declare const validateTaiwanTel: (value: string) => boolean;
  * @example
  * ```typescript
  * // Basic telephone number validation
- * const basicSchema = tel()
+ * 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({
+ * 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({ required: false })
+ * const optionalSchema = tel(false)
  * optionalSchema.parse("") // ✓ Valid (returns null)
  * optionalSchema.parse("0223456789") // ✓ Valid
  *
  * // With custom transformation (remove separators)
- * const transformSchema = tel({
+ * 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({
+ * const customSchema = tel(false, {
  *   i18n: {
  *     en: { invalid: "Please enter a valid Taiwan landline number" },
  *     'zh-TW': { invalid: "請輸入有效的台灣市話號碼" }
@@ -2920,7 +2979,7 @@ declare const validateTaiwanTel: (value: string) => boolean;
  * @see {@link TelOptions} for all available configuration options
  * @see {@link validateTaiwanTel} for validation logic details
  */
-declare function tel<IsRequired extends boolean = true>(options?: TelOptions<IsRequired>): TelSchema<IsRequired>;
+declare function tel<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<TelOptions<IsRequired>, 'required'>): TelSchema<IsRequired>;
 
 /**
  * @fileoverview Taiwan Fax Number validator for Zod Kit
@@ -2958,7 +3017,6 @@ type FaxMessages = {
  * @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;
@@ -3011,7 +3069,8 @@ declare const validateTaiwanFax: (value: string) => boolean;
  * Creates a Zod schema for Taiwan fax number validation
  *
  * @template IsRequired - Whether the field is required (affects return type)
- * @param {FaxOptions<IsRequired>} [options] - Configuration options for fax validation
+ * @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
@@ -3031,32 +3090,39 @@ declare const validateTaiwanFax: (value: string) => boolean;
  * @example
  * ```typescript
  * // Basic fax number validation
- * const basicSchema = fax()
+ * 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({
+ * 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({ required: false })
+ * const optionalSchema = fax(false)
  * optionalSchema.parse("") // ✓ Valid (returns null)
  * optionalSchema.parse("0223456789") // ✓ Valid
  *
  * // With custom transformation
- * const transformSchema = fax({
+ * 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({
+ * const customSchema = fax(false, {
  *   i18n: {
  *     en: { invalid: "Please enter a valid Taiwan fax number" },
  *     'zh-TW': { invalid: "請輸入有效的台灣傳真號碼" }
@@ -3068,6 +3134,6 @@ declare const validateTaiwanFax: (value: string) => boolean;
  * @see {@link FaxOptions} for all available configuration options
  * @see {@link validateTaiwanFax} for validation logic details
  */
-declare function fax<IsRequired extends boolean = true>(options?: FaxOptions<IsRequired>): FaxSchema<IsRequired>;
+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, 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 };