@hy_ong/zod-kit 0.1.1 → 0.1.3

package/src/validators/common/id.ts

@@ -8,7 +8,7 @@
  * @version 0.0.5
  */
 
-import { z, ZodNullable, ZodString } from "zod"
+import { z, ZodNullable, ZodString, ZodNumber } from "zod"
 import { t } from "../../i18n"
 import { getLocale, type Locale } from "../../config"
 
@@ -85,10 +85,11 @@ export type IdType =
  * Configuration options for ID validation
  *
  * @template IsRequired - Whether the field is required (affects return type)
+ * @template Type - The ID type being validated
  *
  * @interface IdOptions
  * @property {IsRequired} [required=true] - Whether the field is required
- * @property {IdType} [type="auto"] - Expected ID type or auto-detection
+ * @property {Type} [type="auto"] - Expected ID type or auto-detection
  * @property {number} [minLength] - Minimum length of ID
  * @property {number} [maxLength] - Maximum length of ID
  * @property {IdType[]} [allowedTypes] - Multiple allowed ID types (overrides type)
@@ -99,11 +100,11 @@ export type IdType =
  * @property {string} [endsWith] - String that ID must end with
  * @property {boolean} [caseSensitive=true] - Whether validation is case-sensitive
  * @property {Function} [transform] - Custom transformation function for ID
- * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {any} [defaultValue] - Default value when input is empty (string for string types, number for numeric)
  * @property {Record<Locale, IdMessages>} [i18n] - Custom error messages for different locales
  */
-export type IdOptions<IsRequired extends boolean = true> = {
-  type?: IdType
+export type IdOptions<Type extends IdType | undefined = undefined> = {
+  type?: Type
   minLength?: number
   maxLength?: number
   allowedTypes?: IdType[]
@@ -114,18 +115,27 @@ export type IdOptions<IsRequired extends boolean = true> = {
   endsWith?: string
   caseSensitive?: boolean
   transform?: (value: string) => string
-  defaultValue?: IsRequired extends true ? string : string | null
+  defaultValue?: any // Simplified to avoid complex conditional types
   i18n?: Record<Locale, IdMessages>
 }
 
 /**
- * Type alias for ID validation schema based on required flag
+ * Type alias for ID validation schema based on required flag and ID type
  *
  * @template IsRequired - Whether the field is required
+ * @template IdType - The ID type being validated
  * @typedef IdSchema
- * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ * @description Returns appropriate Zod type based on required flag and ID type:
+ * - numeric type: ZodNumber or ZodNullable<ZodNumber>
+ * - other types: ZodString or ZodNullable<ZodString>
  */
-export type IdSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
+export type IdSchema<IsRequired extends boolean, Type extends IdType | undefined = undefined> = Type extends "numeric"
+  ? IsRequired extends true
+    ? ZodNumber
+    : ZodNullable<ZodNumber>
+  : IsRequired extends true
+    ? ZodString
+    : ZodNullable<ZodString>
 
 /**
  * Regular expression patterns for different ID formats
@@ -216,9 +226,9 @@ const validateIdType = (value: string, type: IdType): boolean => {
  * Creates a Zod schema for ID validation with comprehensive format support
  *
  * @template IsRequired - Whether the field is required (affects return type)
+ * @template Type - The ID type being validated (affects return type for numeric)
  * @param {IsRequired} [required=false] - Whether the field is required
- * @param {Omit<ValidatorOptions<IsRequired>, 'required'>} [options] - Configuration options for validation
- * @returns {IdSchema<IsRequired>} Zod schema for ID validation
+ * @returns {IdSchema<IsRequired, Type>} Zod schema for ID validation
  *
  * @description
  * Creates a comprehensive ID validator with support for multiple ID formats,
@@ -286,27 +296,31 @@ const validateIdType = (value: string, type: IdType): boolean => {
  * @see {@link detectIdType} for auto-detection logic
  * @see {@link validateIdType} for type-specific validation
  */
-export function id<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<IdOptions<IsRequired>, 'required'>): IdSchema<IsRequired> {
-  const {
-    type = "auto",
-    minLength,
-    maxLength,
-    allowedTypes,
-    customRegex,
-    includes,
-    excludes,
-    startsWith,
-    endsWith,
-    caseSensitive = true,
-    transform,
-    defaultValue,
-    i18n,
-  } = options ?? {}
-
-  const isRequired = required ?? false as IsRequired
-
-  // Set appropriate default value based on required flag
-  const actualDefaultValue = defaultValue ?? (isRequired ? "" : null)
+// Overload: no options provided
+export function id<IsRequired extends boolean = false>(required?: IsRequired): IdSchema<IsRequired, undefined>
+
+// Overload: options with numeric type
+export function id<IsRequired extends boolean = false>(required: IsRequired, options: Omit<IdOptions<"numeric">, "required"> & { type: "numeric" }): IdSchema<IsRequired, "numeric">
+
+// Overload: options with other specific type
+export function id<IsRequired extends boolean = false, Type extends Exclude<IdType, "numeric"> = Exclude<IdType, "numeric">>(
+  required: IsRequired,
+  options: Omit<IdOptions<Type>, "required"> & { type: Type }
+): IdSchema<IsRequired, Type>
+
+// Overload: options without type specified
+export function id<IsRequired extends boolean = false>(required: IsRequired, options: Omit<IdOptions, "required"> & { type?: never }): IdSchema<IsRequired, undefined>
+
+// Implementation
+export function id<IsRequired extends boolean = false, Type extends IdType | undefined = undefined>(required?: IsRequired, options?: any): any {
+  const { type = "auto" as Type, minLength, maxLength, allowedTypes, customRegex, includes, excludes, startsWith, endsWith, caseSensitive = true, transform, defaultValue, i18n } = options ?? {}
+
+  const isRequired = (required ?? false) as IsRequired
+  const isNumericType = type === "numeric"
+
+  // Set appropriate default value based on required flag and type
+  // For required fields, we don't set a default unless explicitly provided
+  const actualDefaultValue = defaultValue !== undefined ? defaultValue : isRequired ? (isNumericType ? NaN : "") : null
 
   // Helper function to get custom message or fallback to default i18n
   const getMessage = (key: keyof IdMessages, params?: Record<string, any>) => {
@@ -315,14 +329,30 @@ export function id<IsRequired extends boolean = false>(required?: IsRequired, op
       const customMessages = i18n[currentLocale]
       if (customMessages && customMessages[key]) {
         const template = customMessages[key]!
-        return template.replace(/\$\{(\w+)}/g, (_, k) => params?.[k] ?? "")
+        return template.replace(/\$\{(\w+)}/g, (_match: string, k: string) => params?.[k] ?? "")
       }
     }
     return t(`common.id.${key}`, params)
   }
 
-  // Preprocessing function
-  const preprocessFn = (val: unknown) => {
+  // Preprocessing function for numeric type
+  const preprocessNumericFn = (val: unknown) => {
+    // Handle empty/null values
+    if (val === "" || val === null || val === undefined) {
+      // If required and no default, return a special marker that will fail validation
+      if (isRequired && defaultValue === undefined) {
+        // Return undefined to trigger required error in refine
+        return undefined as any
+      }
+      return actualDefaultValue
+    }
+
+    // Try to convert to number and return (even if NaN) so it can be validated by the schema
+    return Number(val)
+  }
+
+  // Preprocessing function for string type
+  const preprocessStringFn = (val: unknown) => {
     if (val === "" || val === null || val === undefined) {
       return actualDefaultValue
     }
@@ -336,15 +366,56 @@ export function id<IsRequired extends boolean = false>(required?: IsRequired, op
     return processed
   }
 
-  const baseSchema = isRequired ? z.preprocess(preprocessFn, z.string()) : z.preprocess(preprocessFn, z.string().nullable())
+  // Create base schema based on type
+  if (isNumericType) {
+    // Use z.any() to avoid Zod's built-in type checking, then validate manually
+    const numericSchema = z.preprocess(preprocessNumericFn, z.any()).superRefine((val, ctx) => {
+      // Allow null for optional fields
+      if (!isRequired && val === null) return
+
+      // Required check for undefined/null/empty (empty string when required)
+      if (val === undefined || (isRequired && val === null)) {
+        ctx.addIssue({ code: "custom", message: getMessage("required") })
+        return
+      }
+
+      // Numeric validation - check if it's an actual number (not NaN)
+      if (typeof val !== "number" || isNaN(val)) {
+        ctx.addIssue({ code: "custom", message: getMessage("numeric") })
+        return
+      }
+
+      // Length checks on string representation
+      const strVal = String(val)
+      if (!ID_PATTERNS.numeric.test(strVal)) {
+        ctx.addIssue({ code: "custom", message: getMessage("numeric") })
+        return
+      }
+
+      if (minLength !== undefined && strVal.length < minLength) {
+        ctx.addIssue({ code: "custom", message: getMessage("minLength", { minLength }) })
+        return
+      }
+      if (maxLength !== undefined && strVal.length > maxLength) {
+        ctx.addIssue({ code: "custom", message: getMessage("maxLength", { maxLength }) })
+        return
+      }
+    })
+
+    return numericSchema as unknown as IdSchema<IsRequired, Type>
+  }
+
+  // String-based ID validation
+  const baseSchema = isRequired ? z.preprocess(preprocessStringFn, z.string()) : z.preprocess(preprocessStringFn, z.string().nullable())
 
   const schema = baseSchema
-    .refine((val) => {
-      if (val === null) return true
+    .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
       }
 
       // Create comparison value for case-insensitive checks
@@ -352,10 +423,12 @@ export function id<IsRequired extends boolean = false>(required?: IsRequired, op
 
       // 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
       }
 
       // Check if we have content-based validations that override format checking
@@ -364,7 +437,8 @@ export function id<IsRequired extends boolean = false>(required?: IsRequired, op
       // Custom regex validation (overrides ID format validation)
       if (val !== null && customRegex !== undefined) {
         if (!customRegex.test(val)) {
-          throw new z.ZodError([{ code: "custom", message: getMessage("customFormat"), path: [] }])
+          ctx.addIssue({ code: "custom", message: getMessage("customFormat") })
+          return
         }
       } else if (val !== null && !hasContentValidations) {
         // ID type validation (only if no custom regex or content validations)
@@ -372,35 +446,40 @@ export function id<IsRequired extends boolean = false>(required?: IsRequired, op
 
         if (allowedTypes && allowedTypes.length > 0) {
           // Check if ID matches any of the allowed types
-          isValidId = allowedTypes.some((allowedType) => validateIdType(val, allowedType))
+          isValidId = allowedTypes.some((allowedType: IdType) => validateIdType(val, allowedType))
           if (!isValidId) {
             const typeNames = allowedTypes.join(", ")
-            throw new z.ZodError([{ code: "custom", message: getMessage("invalid") + ` (allowed types: ${typeNames})`, path: [] }])
+            ctx.addIssue({ code: "custom", message: getMessage("invalid") + ` (allowed types: ${typeNames})` })
+            return
           }
-        } else if (type !== "auto") {
+        } else if (type && type !== "auto") {
           // Validate specific type
           isValidId = validateIdType(val, type)
           if (!isValidId) {
-            throw new z.ZodError([{ code: "custom", message: getMessage(type as keyof IdMessages) || getMessage("invalid"), path: [] }])
+            ctx.addIssue({ code: "custom", message: getMessage(type as keyof IdMessages) || getMessage("invalid") })
+            return
           }
         } else {
           // Auto-detection - must match at least one known pattern
           isValidId = detectIdType(val) !== null
           if (!isValidId) {
-            throw new z.ZodError([{ code: "custom", message: getMessage("invalid"), path: [] }])
+            ctx.addIssue({ code: "custom", message: getMessage("invalid") })
+            return
           }
         }
-      } else if (val !== null && hasContentValidations && type !== "auto" && !customRegex) {
+      } else if (val !== null && hasContentValidations && type && type !== "auto" && !customRegex) {
         // Still validate specific types even with content validations (but not auto)
         if (allowedTypes && allowedTypes.length > 0) {
-          const isValidType = allowedTypes.some((allowedType) => validateIdType(val, allowedType))
+          const isValidType = allowedTypes.some((allowedType: IdType) => validateIdType(val, allowedType))
           if (!isValidType) {
             const typeNames = allowedTypes.join(", ")
-            throw new z.ZodError([{ code: "custom", message: getMessage("invalid") + ` (allowed types: ${typeNames})`, path: [] }])
+            ctx.addIssue({ code: "custom", message: getMessage("invalid") + ` (allowed types: ${typeNames})` })
+            return
           }
         } else {
           if (!validateIdType(val, type)) {
-            throw new z.ZodError([{ code: "custom", message: getMessage(type as keyof IdMessages) || getMessage("invalid"), path: [] }])
+            ctx.addIssue({ code: "custom", message: getMessage(type as keyof IdMessages) || getMessage("invalid") })
+            return
           }
         }
       }
@@ -411,25 +490,27 @@ export function id<IsRequired extends boolean = false>(required?: IsRequired, op
       const searchIncludes = !caseSensitive && includes ? includes.toLowerCase() : includes
 
       if (val !== null && startsWith !== undefined && !comparisonVal.startsWith(searchStartsWith!)) {
-        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 && !comparisonVal.endsWith(searchEndsWith!)) {
-        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 && !comparisonVal.includes(searchIncludes!)) {
-        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) {
           const searchExclude = !caseSensitive ? exclude.toLowerCase() : exclude
           if (comparisonVal.includes(searchExclude)) {
-            throw new z.ZodError([{ code: "custom", message: getMessage("excludes", { excludes: exclude }), path: [] }])
+            ctx.addIssue({ code: "custom", message: getMessage("excludes", { excludes: exclude }) })
+            return
           }
         }
       }
-
-      return true
     })
     .transform((val) => {
       if (val === null) return val
@@ -444,7 +525,7 @@ export function id<IsRequired extends boolean = false>(required?: IsRequired, op
       return val // preserve the original case for UUID/ObjectId or when case-sensitive
     })
 
-  return schema as unknown as IdSchema<IsRequired>
+  return schema as unknown as IdSchema<IsRequired, Type>
 }
 
 /**

package/src/validators/common/number.ts

@@ -98,6 +98,7 @@ export type NumberSchema<IsRequired extends boolean> = IsRequired extends true ?
  * Creates a Zod schema for number validation with comprehensive constraints
  *
  * @template IsRequired - Whether the field is required (affects return type)
+ * @param required
  * @param {NumberOptions<IsRequired>} [options] - Configuration options for number validation
  * @returns {NumberSchema<IsRequired>} Zod schema for number validation
  *
@@ -165,25 +166,10 @@ export type NumberSchema<IsRequired extends boolean> = IsRequired extends true ?
  * @throws {z.ZodError} When validation fails with specific error messages
  * @see {@link NumberOptions} for all available configuration options
  */
-export function number<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<NumberOptions<IsRequired>, 'required'>): NumberSchema<IsRequired> {
-  const {
-    min,
-    max,
-    defaultValue,
-    type = "both",
-    positive,
-    negative,
-    nonNegative,
-    nonPositive,
-    multipleOf,
-    precision,
-    finite = true,
-    transform,
-    parseCommas = false,
-    i18n,
-  } = options ?? {}
+export function number<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<NumberOptions<IsRequired>, "required">): NumberSchema<IsRequired> {
+  const { min, max, defaultValue, type = "both", positive, negative, nonNegative, nonPositive, multipleOf, precision, finite = true, transform, parseCommas = false, i18n } = options ?? {}
 
-  const isRequired = required ?? false as IsRequired
+  const isRequired = required ?? (false as IsRequired)
 
   // Helper function to get custom message or fallback to default i18n
   const getMessage = (key: keyof NumberMessages, params?: Record<string, any>) => {
@@ -243,79 +229,130 @@ export function number<IsRequired extends boolean = false>(required?: IsRequired
       },
       z.union([z.number(), z.null(), z.nan(), z.custom<number>((val) => val === Infinity || val === -Infinity)])
     )
-    .refine((val) => {
+    .superRefine((val, ctx) => {
       // Required check first
       if (isRequired && val === null) {
-        throw new z.ZodError([{ code: "custom", message: getMessage("required"), path: [] }])
+        ctx.addIssue({
+          code: "custom",
+          message: getMessage("required"),
+        })
+        return
       }
 
-      if (val === null) return true
+      if (val === null) return
 
       // Type validation for invalid inputs (NaN)
-      if (typeof val === "number" && isNaN(val)) {
+      if (isNaN(val)) {
         if (type === "integer") {
-          throw new z.ZodError([{ code: "custom", message: getMessage("integer"), path: [] }])
+          ctx.addIssue({
+            code: "custom",
+            message: getMessage("integer"),
+          })
         } else if (type === "float") {
-          throw new z.ZodError([{ code: "custom", message: getMessage("float"), path: [] }])
+          ctx.addIssue({
+            code: "custom",
+            message: getMessage("float"),
+          })
         } else {
-          throw new z.ZodError([{ code: "custom", message: getMessage("invalid"), path: [] }])
+          ctx.addIssue({
+            code: "custom",
+            message: getMessage("invalid"),
+          })
         }
-      }
-
-      // Invalid number check for non-numbers
-      if (typeof val !== "number") {
-        throw new z.ZodError([{ code: "custom", message: getMessage("invalid"), path: [] }])
+        return
       }
 
       // Finite check
       if (finite && !Number.isFinite(val)) {
-        throw new z.ZodError([{ code: "custom", message: getMessage("finite"), path: [] }])
+        ctx.addIssue({
+          code: "custom",
+          message: getMessage("finite"),
+        })
+        return
       }
 
       // Type validation for valid numbers
       if (type === "integer" && !Number.isInteger(val)) {
-        throw new z.ZodError([{ code: "custom", message: getMessage("integer"), path: [] }])
+        ctx.addIssue({
+          code: "custom",
+          message: getMessage("integer"),
+        })
+        return
       }
       if (type === "float" && Number.isInteger(val)) {
-        throw new z.ZodError([{ code: "custom", message: getMessage("float"), path: [] }])
+        ctx.addIssue({
+          code: "custom",
+          message: getMessage("float"),
+        })
+        return
       }
 
       // Sign checks (more specific, should come first)
       if (positive && val <= 0) {
-        throw new z.ZodError([{ code: "custom", message: getMessage("positive"), path: [] }])
+        ctx.addIssue({
+          code: "custom",
+          message: getMessage("positive"),
+        })
+        return
       }
       if (negative && val >= 0) {
-        throw new z.ZodError([{ code: "custom", message: getMessage("negative"), path: [] }])
+        ctx.addIssue({
+          code: "custom",
+          message: getMessage("negative"),
+        })
+        return
       }
       if (nonNegative && val < 0) {
-        throw new z.ZodError([{ code: "custom", message: getMessage("nonNegative"), path: [] }])
+        ctx.addIssue({
+          code: "custom",
+          message: getMessage("nonNegative"),
+        })
+        return
       }
       if (nonPositive && val > 0) {
-        throw new z.ZodError([{ code: "custom", message: getMessage("nonPositive"), path: [] }])
+        ctx.addIssue({
+          code: "custom",
+          message: getMessage("nonPositive"),
+        })
+        return
       }
 
       // Range checks
       if (min !== undefined && val < min) {
-        throw new z.ZodError([{ code: "custom", message: getMessage("min", { min }), path: [] }])
+        ctx.addIssue({
+          code: "custom",
+          message: getMessage("min", { min }),
+        })
+        return
       }
       if (max !== undefined && val > max) {
-        throw new z.ZodError([{ code: "custom", message: getMessage("max", { max }), path: [] }])
+        ctx.addIssue({
+          code: "custom",
+          message: getMessage("max", { max }),
+        })
+        return
       }
 
       // Multiple of check
       if (multipleOf !== undefined && val % multipleOf !== 0) {
-        throw new z.ZodError([{ code: "custom", message: getMessage("multipleOf", { multipleOf }), path: [] }])
+        ctx.addIssue({
+          code: "custom",
+          message: getMessage("multipleOf", { multipleOf }),
+        })
+        return
       }
 
       // Precision check
       if (precision !== undefined) {
         const decimalPlaces = (val.toString().split(".")[1] || "").length
         if (decimalPlaces > precision) {
-          throw new z.ZodError([{ code: "custom", message: getMessage("precision", { precision }), path: [] }])
+          ctx.addIssue({
+            code: "custom",
+            message: getMessage("precision", { precision }),
+          })
+          return
         }
       }
-
-      return true
     })
 
   return schema as unknown as NumberSchema<IsRequired>

package/src/validators/common/password.ts

@@ -320,45 +320,55 @@ export function password<IsRequired extends boolean = false>(required?: IsRequir
 
   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
     }
 
     // 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
     }
 
     // Character requirements
     if (val !== null && uppercase && !/[A-Z]/.test(val)) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("uppercase"), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("uppercase") })
+      return
     }
     if (val !== null && lowercase && !/[a-z]/.test(val)) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("lowercase"), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("lowercase") })
+      return
     }
     if (val !== null && digits && !/[0-9]/.test(val)) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("digits"), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("digits") })
+      return
     }
     if (val !== null && special && !/[!@#$%^&*()_+\-=[\]{};':"\\|,.<>/?]/.test(val)) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("special"), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("special") })
+      return
     }
 
     // Advanced security checks
     if (val !== null && noRepeating && /(.)\1{2,}/.test(val)) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("noRepeating"), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("noRepeating") })
+      return
     }
     if (val !== null && noSequential && /(?:abc|bcd|cde|def|efg|fgh|ghi|hij|ijk|jkl|klm|lmn|mno|nop|opq|pqr|qrs|rst|stu|tuv|uvw|vwx|wxy|xyz|012|123|234|345|456|567|678|789)/i.test(val)) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("noSequential"), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("noSequential") })
+      return
     }
     if (val !== null && noCommonWords && COMMON_PASSWORDS.some((common) => val.toLowerCase().includes(common.toLowerCase()))) {
-      throw new z.ZodError([{ code: "custom", message: getMessage("noCommonWords"), path: [] }])
+      ctx.addIssue({ code: "custom", message: getMessage("noCommonWords") })
+      return
     }
     if (val !== null && minStrength) {
       const strength = calculatePasswordStrength(val)
@@ -366,27 +376,29 @@ export function password<IsRequired extends boolean = false>(required?: IsRequir
       const currentLevel = strengthLevels.indexOf(strength)
       const requiredLevel = strengthLevels.indexOf(minStrength)
       if (currentLevel < requiredLevel) {
-        throw new z.ZodError([{ code: "custom", message: getMessage("minStrength", { minStrength }), path: [] }])
+        ctx.addIssue({ code: "custom", message: getMessage("minStrength", { minStrength }) })
+        return
       }
     }
 
     // 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
         }
       }
     }
     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 PasswordSchema<IsRequired>