@hy_ong/zod-kit 0.0.5 → 0.1.0

package/src/validators/common/url.ts

@@ -1,7 +1,40 @@
+/**
+ * @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
+ */
+
 import { z, ZodNullable, ZodString } from "zod"
 import { t } from "../../i18n"
 import { getLocale, type Locale } from "../../config"
 
+/**
+ * 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
+ */
 export type UrlMessages = {
   required?: string
   invalid?: string
@@ -23,8 +56,35 @@ export type UrlMessages = {
   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
+ */
 export type UrlOptions<IsRequired extends boolean = true> = {
-  required?: IsRequired
   min?: number
   max?: number
   includes?: string
@@ -47,11 +107,96 @@ export type UrlOptions<IsRequired extends boolean = true> = {
   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
+ */
 export type UrlSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
 
-export 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
+ */
+export function url<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<UrlOptions<IsRequired>, 'required'>): UrlSchema<IsRequired> {
   const {
-    required = true,
     min,
     max,
     includes,
@@ -74,7 +219,9 @@ export function url<IsRequired extends boolean = true>(options?: UrlOptions<IsRe
     i18n,
   } = options ?? {}
 
-  const actualDefaultValue = defaultValue ?? (required ? "" : null)
+  const isRequired = required ?? false as IsRequired
+
+  const actualDefaultValue = defaultValue ?? (isRequired ? "" : null)
 
   // Helper function to get custom message or fallback to default i18n
   const getMessage = (key: keyof UrlMessages, params?: Record<string, any>) => {
@@ -104,13 +251,13 @@ export function url<IsRequired extends boolean = true>(options?: UrlOptions<IsRe
     return processed
   }
 
-  const baseSchema = required ? z.preprocess(preprocessFn, z.string()) : z.preprocess(preprocessFn, z.string().nullable())
+  const baseSchema = isRequired ? z.preprocess(preprocessFn, z.string()) : z.preprocess(preprocessFn, z.string().nullable())
 
   const schema = baseSchema.refine((val) => {
     if (val === null) return true
 
     // Required check
-    if (required && (val === "" || val === "null" || val === "undefined")) {
+    if (isRequired && (val === "" || val === "null" || val === "undefined")) {
       throw new z.ZodError([{ code: "custom", message: getMessage("required"), path: [] }])
     }
 

package/src/validators/taiwan/business-id.ts

@@ -1,22 +1,79 @@
+/**
+ * @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
+ */
+
 import { z, ZodNullable, ZodString } from "zod"
 import { t } from "../../i18n"
 import { getLocale, type Locale } from "../../config"
 
+/**
+ * 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
+ */
 export 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
+ */
 export 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
+ */
 export type BusinessIdSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
 
-// Taiwan Business ID (統一編號) validation
+/**
+ * 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)
+ * ```
+ */
 const validateTaiwanBusinessId = (value: string): boolean => {
   // Must be exactly 8 digits
   if (!/^\d{8}$/.test(value)) {
@@ -68,16 +125,74 @@ const validateTaiwanBusinessId = (value: string): boolean => {
   return false
 }
 
-export 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
+ */
+export function businessId<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<BusinessIdOptions<IsRequired>, 'required'>): BusinessIdSchema<IsRequired> {
   const {
-    required = true,
     transform,
     defaultValue,
     i18n
   } = options ?? {}
 
+  const isRequired = required ?? false as IsRequired
+
   // Set appropriate default value based on required flag
-  const actualDefaultValue = defaultValue ?? (required ? "" : null)
+  const actualDefaultValue = defaultValue ?? (isRequired ? "" : null)
 
   // Helper function to get custom message or fallback to default i18n
   const getMessage = (key: keyof BusinessIdMessages, params?: Record<string, any>) => {
@@ -112,18 +227,18 @@ export function businessId<IsRequired extends boolean = true>(options?: Business
     return processed
   }
 
-  const baseSchema = required ? z.preprocess(preprocessFn, z.string()) : z.preprocess(preprocessFn, z.string().nullable())
+  const baseSchema = isRequired ? z.preprocess(preprocessFn, z.string()) : z.preprocess(preprocessFn, z.string().nullable())
 
   const schema = baseSchema.refine((val) => {
     if (val === null) return true
 
     // Required check
-    if (required && (val === "" || val === "null" || val === "undefined")) {
+    if (isRequired && (val === "" || val === "null" || val === "undefined")) {
       throw new z.ZodError([{ code: "custom", message: getMessage("required"), path: [] }])
     }
 
     if (val === null) return true
-    if (!required && val === "") return true
+    if (!isRequired && val === "") return true
 
     // Taiwan Business ID format validation (8 digits + checksum)
     if (!validateTaiwanBusinessId(val)) {
@@ -136,5 +251,19 @@ export function businessId<IsRequired extends boolean = true>(options?: Business
   return schema as unknown as BusinessIdSchema<IsRequired>
 }
 
-// Export utility function for external use
+/**
+ * Utility function exported for external use
+ *
+ * @description
+ * The validation function can be used independently for business ID validation
+ * without creating a full Zod schema.
+ *
+ * @example
+ * ```typescript
+ * import { validateTaiwanBusinessId } from './business-id'
+ *
+ * // Direct validation
+ * const isValid = validateTaiwanBusinessId("12345675") // boolean
+ * ```
+ */
 export { validateTaiwanBusinessId }

package/src/validators/taiwan/fax.ts

@@ -1,24 +1,93 @@
+/**
+ * @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
+ */
+
 import { z, ZodNullable, ZodString } from "zod"
 import { t } from "../../i18n"
 import { getLocale, type Locale } from "../../config"
 
+/**
+ * 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
+ */
 export 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
+ */
 export 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
+ */
 export type FaxSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
 
-// Taiwan fax number validation (Official 2024 rules - same as landline)
+/**
+ * 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)
+ * ```
+ */
 const validateTaiwanFax = (value: string): boolean => {
   // Official Taiwan fax formats according to telecom numbering plan (same as landline):
   // 02: Taipei, New Taipei, Keelung - 8 digits (2&3&5~8+7D)
@@ -97,11 +166,82 @@ const validateTaiwanFax = (value: string): boolean => {
   return false
 }
 
-export function fax<IsRequired extends boolean = true>(options?: FaxOptions<IsRequired>): FaxSchema<IsRequired> {
-  const { required = true, whitelist, transform, defaultValue, i18n } = options ?? {}
+/**
+ * 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
+ */
+export function fax<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<FaxOptions<IsRequired>, 'required'>): FaxSchema<IsRequired> {
+  const { whitelist, transform, defaultValue, i18n } = options ?? {}
+
+  const isRequired = required ?? false as IsRequired
 
   // Set appropriate default value based on required flag
-  const actualDefaultValue = defaultValue ?? (required ? "" : null)
+  const actualDefaultValue = defaultValue ?? (isRequired ? "" : null)
 
   // Helper function to get custom message or fallback to default i18n
   const getMessage = (key: keyof FaxMessages, params?: Record<string, any>) => {
@@ -131,7 +271,7 @@ export function fax<IsRequired extends boolean = true>(options?: FaxOptions<IsRe
         return ""
       }
       // If the field is optional and empty string not in allowlist, return default value
-      if (!required) {
+      if (!isRequired) {
         return actualDefaultValue
       }
       // If a field is required, return the default value (will be validated later)
@@ -145,18 +285,18 @@ export function fax<IsRequired extends boolean = true>(options?: FaxOptions<IsRe
     return processed
   }
 
-  const baseSchema = required ? z.preprocess(preprocessFn, z.string()) : z.preprocess(preprocessFn, z.string().nullable())
+  const baseSchema = isRequired ? z.preprocess(preprocessFn, z.string()) : z.preprocess(preprocessFn, z.string().nullable())
 
   const schema = baseSchema.refine((val) => {
     if (val === null) return true
 
     // Required check
-    if (required && (val === "" || val === "null" || val === "undefined")) {
+    if (isRequired && (val === "" || val === "null" || val === "undefined")) {
       throw new z.ZodError([{ code: "custom", message: getMessage("required"), path: [] }])
     }
 
     if (val === null) return true
-    if (!required && val === "") return true
+    if (!isRequired && val === "") return true
 
     // Allowlist check (if an allowlist is provided, only allow values in the allowlist)
     if (whitelist && whitelist.length > 0) {
@@ -178,5 +318,19 @@ export function fax<IsRequired extends boolean = true>(options?: FaxOptions<IsRe
   return schema as unknown as FaxSchema<IsRequired>
 }
 
-// Export utility function for external use
+/**
+ * Utility function exported for external use
+ *
+ * @description
+ * The validation function can be used independently for fax number validation
+ * without creating a full Zod schema.
+ *
+ * @example
+ * ```typescript
+ * import { validateTaiwanFax } from './fax'
+ *
+ * // Direct validation
+ * const isValid = validateTaiwanFax("0223456789") // boolean
+ * ```
+ */
 export { validateTaiwanFax }