@hy_ong/zod-kit 0.1.2 → 0.1.4

package/src/validators/common/url.ts

@@ -253,12 +253,13 @@ export function url<IsRequired extends boolean = false>(required?: IsRequired, o
 
   const baseSchema = isRequired ? z.preprocess(preprocessFn, z.string()) : z.preprocess(preprocessFn, z.string().nullable())
 
-  const schema = baseSchema.refine((val) => {
-    if (val === null) return true
+  const schema = baseSchema.superRefine((val, ctx) => {
+    if (val === null) return
 
     // Required check
     if (isRequired && (val === "" || val === "null" || val === "undefined")) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("required"), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("required") })
+      return
     }
 
     // URL format validation
@@ -266,88 +267,104 @@ export function url<IsRequired extends boolean = false>(required?: IsRequired, o
     try {
       urlObj = new URL(val)
     } catch {
-      throw new z.ZodError([{ code: "custom", message: getMessage("invalid"), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("invalid") })
+      return
     }
 
     // Length checks
     if (val !== null && min !== undefined && val.length < min) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("min", { min }), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("min", { min }) })
+      return
     }
     if (val !== null && max !== undefined && val.length > max) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("max", { max }), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("max", { max }) })
+      return
     }
 
     // String content checks
     if (val !== null && includes !== undefined && !val.includes(includes)) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("includes", { includes }), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("includes", { includes }) })
+      return
     }
     if (val !== null && excludes !== undefined) {
       const excludeList = Array.isArray(excludes) ? excludes : [excludes]
       for (const exclude of excludeList) {
         if (val.includes(exclude)) {
-          throw new z.ZodError([{ code: "custom", message: getMessage("excludes", { excludes: exclude }), path: [] }])
+          ctx.addIssue({ code: "custom", message: getMessage("excludes", { excludes: exclude }) })
+          return
         }
       }
     }
 
     // Protocol validation
     if (protocols && !protocols.includes(urlObj.protocol.slice(0, -1))) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("protocol", { protocols: protocols.join(", ") }), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("protocol", { protocols: protocols.join(", ") }) })
+      return
     }
 
     // Domain validation
     const hostname = urlObj.hostname.toLowerCase()
     if (allowedDomains && !allowedDomains.some((domain) => hostname === domain || hostname.endsWith(`.${domain}`))) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("domain", { domains: allowedDomains.join(", ") }), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("domain", { domains: allowedDomains.join(", ") }) })
+      return
     }
     if (blockedDomains && blockedDomains.some((domain) => hostname === domain || hostname.endsWith(`.${domain}`))) {
       const blockedDomain = blockedDomains.find((domain) => hostname === domain || hostname.endsWith(`.${domain}`))
-      throw new z.ZodError([{ code: "custom", message: getMessage("domainBlacklist", { domain: blockedDomain }), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("domainBlacklist", { domain: blockedDomain }) })
+      return
     }
 
     // Port validation
     const port = urlObj.port ? parseInt(urlObj.port) : urlObj.protocol === "https:" ? 443 : 80
     if (allowedPorts && !allowedPorts.includes(port)) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("port", { ports: allowedPorts.join(", ") }), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("port", { ports: allowedPorts.join(", ") }) })
+      return
     }
     if (blockedPorts && blockedPorts.includes(port)) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("port", { port }), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("port", { port }) })
+      return
     }
 
     // Path validation
     if (pathStartsWith && !urlObj.pathname.startsWith(pathStartsWith)) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("pathStartsWith", { path: pathStartsWith }), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("pathStartsWith", { path: pathStartsWith }) })
+      return
     }
     if (pathEndsWith && !urlObj.pathname.endsWith(pathEndsWith)) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("pathEndsWith", { path: pathEndsWith }), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("pathEndsWith", { path: pathEndsWith }) })
+      return
     }
 
     // Query validation
     if (mustHaveQuery && !urlObj.search) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("hasQuery"), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("hasQuery") })
+      return
     }
     if (mustNotHaveQuery && urlObj.search) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("noQuery"), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("noQuery") })
+      return
     }
 
     // Fragment validation
     if (mustHaveFragment && !urlObj.hash) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("hasFragment"), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("hasFragment") })
+      return
     }
     if (mustNotHaveFragment && urlObj.hash) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("noFragment"), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("noFragment") })
+      return
     }
 
     // Localhost validation
     const isLocalhost = hostname === "localhost" || hostname === "127.0.0.1" || hostname.startsWith("192.168.") || hostname.startsWith("10.") || hostname.match(/^172\.(1[6-9]|2[0-9]|3[0-1])\./)
     if (blockLocalhost && isLocalhost) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("noLocalhost"), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("noLocalhost") })
+      return
     }
     if (!allowLocalhost && isLocalhost) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("localhost"), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("localhost") })
+      return
     }
-
-    return true
   })
 
   return schema as unknown as UrlSchema<IsRequired>

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

@@ -15,11 +15,11 @@ import { getLocale, type Locale } from "../../config"
 /**
  * Type definition for business ID validation error messages
  *
- * @interface BusinessIdMessages
+ * @interface TwBusinessIdMessages
  * @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 = {
+export type TwBusinessIdMessages = {
   required?: string
   invalid?: string
 }
@@ -29,26 +29,26 @@ export type BusinessIdMessages = {
  *
  * @template IsRequired - Whether the field is required (affects return type)
  *
- * @interface BusinessIdOptions
+ * @interface TwBusinessIdOptions
  * @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
+ * @property {Record<Locale, TwBusinessIdMessages>} [i18n] - Custom error messages for different locales
  */
-export type BusinessIdOptions<IsRequired extends boolean = true> = {
+export type TwBusinessIdOptions<IsRequired extends boolean = true> = {
   transform?: (value: string) => string
   defaultValue?: IsRequired extends true ? string : string | null
-  i18n?: Record<Locale, BusinessIdMessages>
+  i18n?: Record<Locale, TwBusinessIdMessages>
 }
 
 /**
  * Type alias for business ID validation schema based on required flag
  *
  * @template IsRequired - Whether the field is required
- * @typedef BusinessIdSchema
+ * @typedef TwBusinessIdSchema
  * @description Returns ZodString if required, ZodNullable<ZodString> if optional
  */
-export type BusinessIdSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
+export type TwBusinessIdSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
 
 /**
  * Validates Taiwan Business Identification Number (統一編號)
@@ -80,7 +80,7 @@ const validateTaiwanBusinessId = (value: string): boolean => {
     return false
   }
 
-  const digits = value.split('').map(Number)
+  const digits = value.split("").map(Number)
 
   // Coefficients for the first 7 digits
   const coefficients = [1, 2, 1, 2, 1, 2, 4]
@@ -179,23 +179,19 @@ const validateTaiwanBusinessId = (value: string): boolean => {
  * ```
  *
  * @throws {z.ZodError} When validation fails with specific error messages
- * @see {@link BusinessIdOptions} for all available configuration options
+ * @see {@link TwBusinessIdOptions} 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 {
-    transform,
-    defaultValue,
-    i18n
-  } = options ?? {}
+export function twBusinessId<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<TwBusinessIdOptions<IsRequired>, "required">): TwBusinessIdSchema<IsRequired> {
+  const { transform, defaultValue, i18n } = options ?? {}
 
-  const isRequired = required ?? false as IsRequired
+  const isRequired = required ?? (false as IsRequired)
 
   // Set appropriate default value based on required flag
   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>) => {
+  const getMessage = (key: keyof TwBusinessIdMessages, params?: Record<string, any>) => {
     if (i18n) {
       const currentLocale = getLocale()
       const customMessages = i18n[currentLocale]
@@ -229,26 +225,26 @@ export function businessId<IsRequired extends boolean = false>(required?: IsRequ
 
   const baseSchema = isRequired ? z.preprocess(preprocessFn, z.string()) : z.preprocess(preprocessFn, z.string().nullable())
 
-  const schema = baseSchema.refine((val) => {
-    if (val === null) return true
+  const schema = baseSchema.superRefine((val, ctx) => {
+    if (val === null) return
 
     // Required check
     if (isRequired && (val === "" || val === "null" || val === "undefined")) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("required"), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("required") })
+      return
     }
 
-    if (val === null) return true
-    if (!isRequired && val === "") return true
+    if (val === null) return
+    if (!isRequired && val === "") return
 
     // Taiwan Business ID format validation (8 digits + checksum)
     if (!validateTaiwanBusinessId(val)) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("invalid"), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("invalid") })
+      return
     }
-
-    return true
   })
 
-  return schema as unknown as BusinessIdSchema<IsRequired>
+  return schema as unknown as TwBusinessIdSchema<IsRequired>
 }
 
 /**
@@ -266,4 +262,4 @@ export function businessId<IsRequired extends boolean = false>(required?: IsRequ
  * const isValid = validateTaiwanBusinessId("12345675") // boolean
  * ```
  */
-export { validateTaiwanBusinessId }
+export { validateTaiwanBusinessId }

package/src/validators/taiwan/fax.ts

@@ -15,12 +15,12 @@ import { getLocale, type Locale } from "../../config"
 /**
  * Type definition for fax number validation error messages
  *
- * @interface FaxMessages
+ * @interface TwFaxMessages
  * @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 = {
+export type TwFaxMessages = {
   required?: string
   invalid?: string
   notInWhitelist?: string
@@ -31,28 +31,28 @@ export type FaxMessages = {
  *
  * @template IsRequired - Whether the field is required (affects return type)
  *
- * @interface FaxOptions
+ * @interface TwFaxOptions
  * @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
+ * @property {Record<Locale, TwFaxMessages>} [i18n] - Custom error messages for different locales
  */
-export type FaxOptions<IsRequired extends boolean = true> = {
+export type TwFaxOptions<IsRequired extends boolean = true> = {
   whitelist?: string[]
   transform?: (value: string) => string
   defaultValue?: IsRequired extends true ? string : string | null
-  i18n?: Record<Locale, FaxMessages>
+  i18n?: Record<Locale, TwFaxMessages>
 }
 
 /**
  * Type alias for fax number validation schema based on required flag
  *
  * @template IsRequired - Whether the field is required
- * @typedef FaxSchema
+ * @typedef TwFaxSchema
  * @description Returns ZodString if required, ZodNullable<ZodString> if optional
  */
-export type FaxSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
+export type TwFaxSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
 
 /**
  * Validates Taiwan fax number format (Official 2024 rules - same as landline)
@@ -172,7 +172,7 @@ const validateTaiwanFax = (value: string): boolean => {
  * @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
+ * @returns {TwFaxSchema<IsRequired>} Zod schema for fax number validation
  *
  * @description
  * Creates a comprehensive Taiwan fax number validator with support for all Taiwan
@@ -191,7 +191,7 @@ const validateTaiwanFax = (value: string): boolean => {
  * @example
  * ```typescript
  * // Basic fax number validation
- * const basicSchema = fax() // optional by default
+ * const basicSchema = twFax() // optional by default
  * basicSchema.parse("0223456789") // ✓ Valid (Taipei)
  * basicSchema.parse(null) // ✓ Valid (optional)
  *
@@ -205,25 +205,25 @@ const validateTaiwanFax = (value: string): boolean => {
  * basicSchema.parse("0812345678") // ✗ Invalid (wrong format for 08)
  *
  * // With whitelist (only specific numbers allowed)
- * const whitelistSchema = fax(false, {
+ * const whitelistSchema = twFax(false, {
  *   whitelist: ["0223456789", "0312345678"]
  * })
  * whitelistSchema.parse("0223456789") // ✓ Valid (in whitelist)
  * whitelistSchema.parse("0287654321") // ✗ Invalid (not in whitelist)
  *
  * // Optional fax number
- * const optionalSchema = fax(false)
+ * const optionalSchema = twFax(false)
  * optionalSchema.parse("") // ✓ Valid (returns null)
  * optionalSchema.parse("0223456789") // ✓ Valid
  *
  * // With custom transformation
- * const transformSchema = fax(false, {
+ * const transformSchema = twFax(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, {
+ * const customSchema = twFax(false, {
  *   i18n: {
  *     en: { invalid: "Please enter a valid Taiwan fax number" },
  *     'zh-TW': { invalid: "請輸入有效的台灣傳真號碼" }
@@ -232,10 +232,10 @@ const validateTaiwanFax = (value: string): boolean => {
  * ```
  *
  * @throws {z.ZodError} When validation fails with specific error messages
- * @see {@link FaxOptions} for all available configuration options
+ * @see {@link TwFaxOptions} 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> {
+export function twFax<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<TwFaxOptions<IsRequired>, 'required'>): TwFaxSchema<IsRequired> {
   const { whitelist, transform, defaultValue, i18n } = options ?? {}
 
   const isRequired = required ?? false as IsRequired
@@ -244,7 +244,7 @@ export function fax<IsRequired extends boolean = false>(required?: IsRequired, o
   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>) => {
+  const getMessage = (key: keyof TwFaxMessages, params?: Record<string, any>) => {
     if (i18n) {
       const currentLocale = getLocale()
       const customMessages = i18n[currentLocale]
@@ -287,35 +287,36 @@ export function fax<IsRequired extends boolean = false>(required?: IsRequired, o
 
   const baseSchema = isRequired ? z.preprocess(preprocessFn, z.string()) : z.preprocess(preprocessFn, z.string().nullable())
 
-  const schema = baseSchema.refine((val) => {
-    if (val === null) return true
+  const schema = baseSchema.superRefine((val, ctx) => {
+    if (val === null) return
 
     // Required check
     if (isRequired && (val === "" || val === "null" || val === "undefined")) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("required"), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("required") })
+      return
     }
 
-    if (val === null) return true
-    if (!isRequired && val === "") return true
+    if (val === null) return
+    if (!isRequired && val === "") return
 
     // Allowlist check (if an allowlist is provided, only allow values in the allowlist)
     if (whitelist && whitelist.length > 0) {
       if (whitelist.includes(val)) {
-        return true
+        return
       }
       // If not in the allowlist, reject regardless of format
-      throw new z.ZodError([{ code: "custom", message: getMessage("notInWhitelist"), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("notInWhitelist") })
+      return
     }
 
     // Taiwan fax format validation (only if no allowlist or allowlist is empty)
     if (!validateTaiwanFax(val)) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("invalid"), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("invalid") })
+      return
     }
-
-    return true
   })
 
-  return schema as unknown as FaxSchema<IsRequired>
+  return schema as unknown as TwFaxSchema<IsRequired>
 }
 
 /**

package/src/validators/taiwan/mobile.ts

@@ -15,12 +15,12 @@ import { getLocale, type Locale } from "../../config"
 /**
  * Type definition for mobile phone validation error messages
  *
- * @interface MobileMessages
+ * @interface TwMobileMessages
  * @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
  */
-export type MobileMessages = {
+export type TwMobileMessages = {
   required?: string
   invalid?: string
   notInWhitelist?: string
@@ -31,28 +31,28 @@ export type MobileMessages = {
  *
  * @template IsRequired - Whether the field is required (affects return type)
  *
- * @interface MobileOptions
+ * @interface TwMobileOptions
  * @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
+ * @property {Record<Locale, TwMobileMessages>} [i18n] - Custom error messages for different locales
  */
-export type MobileOptions<IsRequired extends boolean = true> = {
+export type TwMobileOptions<IsRequired extends boolean = true> = {
   whitelist?: string[]
   transform?: (value: string) => string
   defaultValue?: IsRequired extends true ? string : string | null
-  i18n?: Record<Locale, MobileMessages>
+  i18n?: Record<Locale, TwMobileMessages>
 }
 
 /**
  * Type alias for mobile phone validation schema based on required flag
  *
  * @template IsRequired - Whether the field is required
- * @typedef MobileSchema
+ * @typedef TwMobileSchema
  * @description Returns ZodString if required, ZodNullable<ZodString> if optional
  */
-export type MobileSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
+export type TwMobileSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
 
 /**
  * Validates Taiwan mobile phone number format
@@ -88,7 +88,7 @@ const validateTaiwanMobile = (value: string): boolean => {
  * @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
+ * @returns {TwMobileSchema<IsRequired>} Zod schema for mobile phone validation
  *
  * @description
  * Creates a comprehensive Taiwan mobile phone number validator with support for
@@ -106,7 +106,7 @@ const validateTaiwanMobile = (value: string): boolean => {
  * @example
  * ```typescript
  * // Basic mobile number validation
- * const basicSchema = mobile() // optional by default
+ * const basicSchema = twMobile() // optional by default
  * basicSchema.parse("0912345678") // ✓ Valid
  * basicSchema.parse(null) // ✓ Valid (optional)
  *
@@ -119,26 +119,26 @@ const validateTaiwanMobile = (value: string): boolean => {
  * basicSchema.parse("0812345678") // ✗ Invalid (wrong prefix)
  *
  * // With whitelist (only specific numbers allowed)
- * const whitelistSchema = mobile(false, {
+ * const whitelistSchema = twMobile(false, {
  *   whitelist: ["0912345678", "0987654321"]
  * })
  * whitelistSchema.parse("0912345678") // ✓ Valid (in whitelist)
  * whitelistSchema.parse("0911111111") // ✗ Invalid (not in whitelist)
  *
  * // Optional mobile number
- * const optionalSchema = mobile(false)
+ * const optionalSchema = twMobile(false)
  * optionalSchema.parse("") // ✓ Valid (returns null)
  * optionalSchema.parse("0912345678") // ✓ Valid
  *
  * // With custom transformation
- * const transformSchema = mobile(false, {
+ * const transformSchema = twMobile(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, {
+ * const customSchema = twMobile(false, {
  *   i18n: {
  *     en: { invalid: "Please enter a valid Taiwan mobile number" },
  *     'zh-TW': { invalid: "請輸入有效的台灣手機號碼" }
@@ -147,10 +147,10 @@ const validateTaiwanMobile = (value: string): boolean => {
  * ```
  *
  * @throws {z.ZodError} When validation fails with specific error messages
- * @see {@link MobileOptions} for all available configuration options
+ * @see {@link TwMobileOptions} for all available configuration options
  * @see {@link validateTaiwanMobile} for validation logic details
  */
-export function mobile<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<MobileOptions<IsRequired>, 'required'>): MobileSchema<IsRequired> {
+export function twMobile<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<TwMobileOptions<IsRequired>, 'required'>): TwMobileSchema<IsRequired> {
   const { whitelist, transform, defaultValue, i18n } = options ?? {}
 
   const isRequired = required ?? false as IsRequired
@@ -159,7 +159,7 @@ export function mobile<IsRequired extends boolean = false>(required?: IsRequired
   const actualDefaultValue = defaultValue ?? (isRequired ? "" : null)
 
   // Helper function to get custom message or fallback to default i18n
-  const getMessage = (key: keyof MobileMessages, params?: Record<string, any>) => {
+  const getMessage = (key: keyof TwMobileMessages, params?: Record<string, any>) => {
     if (i18n) {
       const currentLocale = getLocale()
       const customMessages = i18n[currentLocale]
@@ -202,35 +202,36 @@ export function mobile<IsRequired extends boolean = false>(required?: IsRequired
 
   const baseSchema = isRequired ? z.preprocess(preprocessFn, z.string()) : z.preprocess(preprocessFn, z.string().nullable())
 
-  const schema = baseSchema.refine((val) => {
-    if (val === null) return true
+  const schema = baseSchema.superRefine((val, ctx) => {
+    if (val === null) return
 
     // Required check
     if (isRequired && (val === "" || val === "null" || val === "undefined")) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("required"), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("required") })
+      return
     }
 
-    if (val === null) return true
-    if (!isRequired && val === "") return true
+    if (val === null) return
+    if (!isRequired && val === "") return
 
     // Allowlist check (if an allowlist is provided, only allow values in the allowlist)
     if (whitelist && whitelist.length > 0) {
       if (whitelist.includes(val)) {
-        return true
+        return
       }
       // If not in the allowlist, reject regardless of format
-      throw new z.ZodError([{ code: "custom", message: getMessage("notInWhitelist"), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("notInWhitelist") })
+      return
     }
 
     // Taiwan mobile phone format validation (only if no allowlist or allowlist is empty)
     if (!validateTaiwanMobile(val)) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("invalid"), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("invalid") })
+      return
     }
-
-    return true
   })
 
-  return schema as unknown as MobileSchema<IsRequired>
+  return schema as unknown as TwMobileSchema<IsRequired>
 }
 
 /**