@hy_ong/zod-kit 0.1.1 → 0.1.3

package/src/validators/common/text.ts

@@ -223,52 +223,86 @@ export function text<IsRequired extends boolean = false>(required?: IsRequired,
 
   const baseSchema = isRequired ? z.preprocess(preprocessFn, z.string()) : z.preprocess(preprocessFn, z.string().nullable())
 
-  // Single refine with all validations for better performance
-  const schema = baseSchema.refine((val) => {
-    if (val === null) return true
+  // Single superRefine with all validations for better performance
+  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
     }
 
     // Not empty check (different from required - checks whitespace)
     // For notEmpty, we need to check if the original string (before processing) was only whitespace
     if (notEmpty && val !== null && val.trim() === "") {
-      throw new z.ZodError([{ code: "custom", message: getMessage("notEmpty"), path: [] }])
+      ctx.addIssue({
+        code: "custom",
+        message: getMessage("notEmpty")
+      })
+      return
     }
 
     // Length checks
     if (val !== null && minLength !== undefined && val.length < minLength) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("minLength", { minLength }), path: [] }])
+      ctx.addIssue({
+        code: "custom",
+        message: getMessage("minLength", { minLength })
+      })
+      return
     }
     if (val !== null && maxLength !== undefined && val.length > maxLength) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("maxLength", { maxLength }), path: [] }])
+      ctx.addIssue({
+        code: "custom",
+        message: getMessage("maxLength", { maxLength })
+      })
+      return
     }
 
     // String content checks
     if (val !== null && startsWith !== undefined && !val.startsWith(startsWith)) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("startsWith", { startsWith }), path: [] }])
+      ctx.addIssue({
+        code: "custom",
+        message: getMessage("startsWith", { startsWith })
+      })
+      return
     }
     if (val !== null && endsWith !== undefined && !val.endsWith(endsWith)) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("endsWith", { endsWith }), path: [] }])
+      ctx.addIssue({
+        code: "custom",
+        message: getMessage("endsWith", { endsWith })
+      })
+      return
     }
     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
         }
       }
     }
     if (val !== null && regex !== undefined && !regex.test(val)) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("invalid", { regex }), path: [] }])
+      ctx.addIssue({
+        code: "custom",
+        message: getMessage("invalid", { regex })
+      })
+      return
     }
-
-    return true
   })
 
   return schema as unknown as TextSchema<IsRequired>

package/src/validators/common/time.ts

@@ -465,25 +465,27 @@ export function time<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
 
     // Whitelist check
     if (whitelist && whitelist.length > 0) {
       if (whitelist.includes(val)) {
-        return true
+        return
       }
       // If whitelistOnly is true, reject values not in whitelist
       if (whitelistOnly) {
-        throw new z.ZodError([{ code: "custom", message: getMessage("notInWhitelist"), path: [] }])
+        ctx.addIssue({ code: "custom", message: getMessage("notInWhitelist") })
+        return
       }
       // Otherwise, continue with normal validation
     }
@@ -491,60 +493,69 @@ export function time<IsRequired extends boolean = false>(required?: IsRequired,
     // Custom regex validation (overrides format validation)
     if (regex) {
       if (!regex.test(val)) {
-        throw new z.ZodError([{ code: "custom", message: getMessage("customRegex"), path: [] }])
+        ctx.addIssue({ code: "custom", message: getMessage("customRegex") })
+        return
       }
     } else {
       // Time format validation (only if no regex is provided)
       if (!validateTimeFormat(val, format)) {
-        throw new z.ZodError([{ code: "custom", message: getMessage("format", { format }), path: [] }])
+        ctx.addIssue({ code: "custom", message: getMessage("format", { format }) })
+        return
       }
     }
 
     // String content checks
     if (includes && !val.includes(includes)) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("includes", { includes }), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("includes", { includes }) })
+      return
     }
 
     if (excludes) {
       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
         }
       }
     }
 
     // Skip time parsing and range validation if using custom regex
     if (regex) {
-      return true
+      return
     }
 
     // Parse time for range validation
     const timeMinutes = parseTimeToMinutes(val, format)
     if (timeMinutes === null) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("invalid"), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("invalid") })
+      return
     }
 
     // Hour validation
     const hour = Math.floor(timeMinutes / 60)
     if (minHour !== undefined && hour < minHour) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("hour", { minHour, maxHour: maxHour ?? 23 }), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("hour", { minHour, maxHour: maxHour ?? 23 }) })
+      return
     }
     if (maxHour !== undefined && hour > maxHour) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("hour", { minHour: minHour ?? 0, maxHour }), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("hour", { minHour: minHour ?? 0, maxHour }) })
+      return
     }
 
     // Allowed hours check
     if (allowedHours && allowedHours.length > 0) {
       if (!allowedHours.includes(hour)) {
-        throw new z.ZodError([{ code: "custom", message: getMessage("hour", { allowedHours: allowedHours.join(", ") }), path: [] }])
+        ctx.addIssue({ code: "custom", message: getMessage("hour", { allowedHours: allowedHours.join(", ") }) })
+        return
       }
     }
 
     // Minute step validation
     const minute = timeMinutes % 60
     if (minuteStep !== undefined && minute % minuteStep !== 0) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("minute", { minuteStep }), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("minute", { minuteStep }) })
+      return
     }
 
     // Second step validation (only for formats with seconds)
@@ -554,7 +565,8 @@ export function time<IsRequired extends boolean = false>(required?: IsRequired,
       if (secondMatch) {
         const seconds = parseInt(secondMatch[1], 10)
         if (seconds % secondStep !== 0) {
-          throw new z.ZodError([{ code: "custom", message: getMessage("second", { secondStep }), path: [] }])
+          ctx.addIssue({ code: "custom", message: getMessage("second", { secondStep }) })
+          return
         }
       }
     }
@@ -563,18 +575,18 @@ export function time<IsRequired extends boolean = false>(required?: IsRequired,
     if (min) {
       const minMinutes = parseTimeToMinutes(min, format)
       if (minMinutes !== null && timeMinutes < minMinutes) {
-        throw new z.ZodError([{ code: "custom", message: getMessage("min", { min }), path: [] }])
+        ctx.addIssue({ code: "custom", message: getMessage("min", { min }) })
+        return
       }
     }
 
     if (max) {
       const maxMinutes = parseTimeToMinutes(max, format)
       if (maxMinutes !== null && timeMinutes > maxMinutes) {
-        throw new z.ZodError([{ code: "custom", message: getMessage("max", { max }), path: [] }])
+        ctx.addIssue({ code: "custom", message: getMessage("max", { max }) })
+        return
       }
     }
-
-    return true
   })
 
   return schema as unknown as TimeSchema<IsRequired>

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 (統一編號)
@@ -179,10 +179,10 @@ 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> {
+export function twBusinessId<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<TwBusinessIdOptions<IsRequired>, 'required'>): TwBusinessIdSchema<IsRequired> {
   const {
     transform,
     defaultValue,
@@ -195,7 +195,7 @@ export function businessId<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 BusinessIdMessages, params?: Record<string, any>) => {
+  const getMessage = (key: keyof TwBusinessIdMessages, params?: Record<string, any>) => {
     if (i18n) {
       const currentLocale = getLocale()
       const customMessages = i18n[currentLocale]
@@ -229,23 +229,23 @@ 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>