@hy_ong/zod-kit 0.1.1 → 0.1.3

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>
 }
 
 /**

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

@@ -15,11 +15,11 @@ import { getLocale, type Locale } from "../../config"
 /**
  * Type definition for national ID validation error messages
  *
- * @interface NationalIdMessages
+ * @interface TwNationalIdMessages
  * @property {string} [required] - Message when field is required but empty
  * @property {string} [invalid] - Message when national ID format or checksum is invalid
  */
-export type NationalIdMessages = {
+export type TwNationalIdMessages = {
   required?: string
   invalid?: string
 }
@@ -44,30 +44,30 @@ export type NationalIdType =
  *
  * @template IsRequired - Whether the field is required (affects return type)
  *
- * @interface NationalIdOptions
+ * @interface TwNationalIdOptions
  * @property {IsRequired} [required=true] - Whether the field is required
  * @property {NationalIdType} [type="both"] - Type of ID to accept
  * @property {boolean} [allowOldResident=true] - Whether to accept old-style resident certificates
  * @property {Function} [transform] - Custom transformation function for ID
  * @property {string | null} [defaultValue] - Default value when input is empty
- * @property {Record<Locale, NationalIdMessages>} [i18n] - Custom error messages for different locales
+ * @property {Record<Locale, TwNationalIdMessages>} [i18n] - Custom error messages for different locales
  */
-export type NationalIdOptions<IsRequired extends boolean = true> = {
+export type TwNationalIdOptions<IsRequired extends boolean = true> = {
   type?: NationalIdType
   allowOldResident?: boolean
   transform?: (value: string) => string
   defaultValue?: IsRequired extends true ? string : string | null
-  i18n?: Record<Locale, NationalIdMessages>
+  i18n?: Record<Locale, TwNationalIdMessages>
 }
 
 /**
  * Type alias for national ID validation schema based on required flag
  *
  * @template IsRequired - Whether the field is required
- * @typedef NationalIdSchema
+ * @typedef TwNationalIdSchema
  * @description Returns ZodString if required, ZodNullable<ZodString> if optional
  */
-export type NationalIdSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
+export type TwNationalIdSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
 
 /**
  * Mapping of Taiwan city/county codes to their numeric values
@@ -268,8 +268,8 @@ const validateTaiwanNationalId = (value: string, type: NationalIdType = "both",
  * Creates a Zod schema for Taiwan National ID validation
  *
  * @template IsRequired - Whether the field is required (affects return type)
- * @param {NationalIdOptions<IsRequired>} [options] - Configuration options for national ID validation
- * @returns {NationalIdSchema<IsRequired>} Zod schema for national ID validation
+ * @param {TwNationalIdOptions<IsRequired>} [options] - Configuration options for national ID validation
+ * @returns {TwNationalIdSchema<IsRequired>} Zod schema for national ID validation
  *
  * @description
  * Creates a comprehensive Taiwan National ID validator that supports both
@@ -288,18 +288,18 @@ const validateTaiwanNationalId = (value: string, type: NationalIdType = "both",
  * @example
  * ```typescript
  * // Accept any valid Taiwan ID
- * const anyIdSchema = nationalId()
+ * const anyIdSchema = twNationalId()
  * anyIdSchema.parse("A123456789") // ✓ Valid citizen ID
  * anyIdSchema.parse("A812345678") // ✓ Valid new resident ID
  * anyIdSchema.parse("AA12345678") // ✓ Valid old resident ID
  *
  * // Citizen IDs only
- * const citizenSchema = nationalId(false, { type: "citizen" })
+ * const citizenSchema = twNationalId(false, { type: "citizen" })
  * citizenSchema.parse("A123456789") // ✓ Valid
  * citizenSchema.parse("A812345678") // ✗ Invalid (resident ID)
  *
  * // Resident IDs only (new format only)
- * const residentSchema = nationalId(false, {
+ * const residentSchema = twNationalId(false, {
  *   type: "resident",
  *   allowOldResident: false
  * })
@@ -307,12 +307,12 @@ const validateTaiwanNationalId = (value: string, type: NationalIdType = "both",
  * residentSchema.parse("AA12345678") // ✗ Invalid (old format)
  *
  * // Optional with custom transformation
- * const optionalSchema = nationalId(false, {
+ * const optionalSchema = twNationalId(false, {
  *   transform: (value) => value.replace(/[^A-Z0-9]/g, '') // Remove special chars
  * })
  *
  * // With custom error messages
- * const customSchema = nationalId(false, {
+ * const customSchema = twNationalId(false, {
  *   i18n: {
  *     en: { invalid: "Please enter a valid Taiwan National ID" },
  *     'zh-TW': { invalid: "請輸入有效的身分證或居留證號碼" }
@@ -321,11 +321,11 @@ const validateTaiwanNationalId = (value: string, type: NationalIdType = "both",
  * ```
  *
  * @throws {z.ZodError} When validation fails with specific error messages
- * @see {@link NationalIdOptions} for all available configuration options
+ * @see {@link TwNationalIdOptions} for all available configuration options
  * @see {@link NationalIdType} for supported ID types
  * @see {@link validateTaiwanNationalId} for validation logic details
  */
-export function nationalId<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<NationalIdOptions<IsRequired>, 'required'>): NationalIdSchema<IsRequired> {
+export function twNationalId<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<TwNationalIdOptions<IsRequired>, 'required'>): TwNationalIdSchema<IsRequired> {
   const {
     type = "both",
     allowOldResident = true,
@@ -340,7 +340,7 @@ export function nationalId<IsRequired extends boolean = false>(required?: IsRequ
   const actualDefaultValue = defaultValue ?? (isRequired ? "" : null)
 
   // Helper function to get custom message or fallback to default i18n
-  const getMessage = (key: keyof NationalIdMessages, params?: Record<string, any>) => {
+  const getMessage = (key: keyof TwNationalIdMessages, params?: Record<string, any>) => {
     if (i18n) {
       const currentLocale = getLocale()
       const customMessages = i18n[currentLocale]
@@ -374,26 +374,26 @@ export function nationalId<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 National ID validation
     if (!validateTaiwanNationalId(val, type, allowOldResident)) {
-      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 NationalIdSchema<IsRequired>
+  return schema as unknown as TwNationalIdSchema<IsRequired>
 }
 
 /**