@hy_ong/zod-kit 0.0.6 → 0.1.1

package/src/validators/common/number.ts

@@ -69,7 +69,6 @@ export type NumberMessages = {
  * @property {Record<Locale, NumberMessages>} [i18n] - Custom error messages for different locales
  */
 export type NumberOptions<IsRequired extends boolean = true> = {
-  required?: IsRequired
   min?: number
   max?: number
   defaultValue?: IsRequired extends true ? number : number | null
@@ -119,53 +118,55 @@ export type NumberSchema<IsRequired extends boolean> = IsRequired extends true ?
  *
  * @example
  * ```typescript
- * // Basic number validation
+ * // Basic number validation (optional by default)
  * const basicSchema = number()
  * basicSchema.parse(42) // ✓ Valid
  * basicSchema.parse("42") // ✓ Valid (converted to number)
+ * basicSchema.parse(null) // ✓ Valid (optional)
+ *
+ * // Required number
+ * const requiredSchema = number(true)
+ * requiredSchema.parse(42) // ✓ Valid
+ * requiredSchema.parse(null) // ✗ Invalid (required)
  *
  * // Integer only
- * const integerSchema = number({ type: "integer" })
+ * const integerSchema = number(false, { type: "integer" })
  * integerSchema.parse(42) // ✓ Valid
  * integerSchema.parse(42.5) // ✗ Invalid
  *
  * // Range validation
- * const rangeSchema = number({ min: 0, max: 100 })
+ * const rangeSchema = number(true, { min: 0, max: 100 })
  * rangeSchema.parse(50) // ✓ Valid
  * rangeSchema.parse(150) // ✗ Invalid
  *
  * // Positive numbers only
- * const positiveSchema = number({ positive: true })
+ * const positiveSchema = number(true, { positive: true })
  * positiveSchema.parse(5) // ✓ Valid
  * positiveSchema.parse(-5) // ✗ Invalid
  *
  * // Multiple of constraint
- * const multipleSchema = number({ multipleOf: 5 })
+ * const multipleSchema = number(true, { multipleOf: 5 })
  * multipleSchema.parse(10) // ✓ Valid
  * multipleSchema.parse(7) // ✗ Invalid
  *
  * // Precision control
- * const precisionSchema = number({ precision: 2 })
+ * const precisionSchema = number(true, { precision: 2 })
  * precisionSchema.parse(3.14) // ✓ Valid
  * precisionSchema.parse(3.14159) // ✗ Invalid
  *
  * // Comma-separated parsing
- * const commaSchema = number({ parseCommas: true })
+ * const commaSchema = number(false, { parseCommas: true })
  * commaSchema.parse("1,234.56") // ✓ Valid (parsed as 1234.56)
  *
  * // Optional with default
- * const optionalSchema = number({
- *   required: false,
- *   defaultValue: 0
- * })
+ * const optionalSchema = number(false, { defaultValue: 0 })
  * ```
  *
  * @throws {z.ZodError} When validation fails with specific error messages
  * @see {@link NumberOptions} for all available configuration options
  */
-export function number<IsRequired extends boolean = true>(options?: NumberOptions<IsRequired>): NumberSchema<IsRequired> {
+export function number<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<NumberOptions<IsRequired>, 'required'>): NumberSchema<IsRequired> {
   const {
-    required = true,
     min,
     max,
     defaultValue,
@@ -182,6 +183,8 @@ export function number<IsRequired extends boolean = true>(options?: NumberOption
     i18n,
   } = options ?? {}
 
+  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>) => {
     if (i18n) {
@@ -242,7 +245,7 @@ export function number<IsRequired extends boolean = true>(options?: NumberOption
     )
     .refine((val) => {
       // Required check first
-      if (required && val === null) {
+      if (isRequired && val === null) {
         throw new z.ZodError([{ code: "custom", message: getMessage("required"), path: [] }])
       }
 

package/src/validators/common/password.ts

@@ -85,7 +85,6 @@ export type PasswordStrength = "weak" | "medium" | "strong" | "very-strong"
  * @property {Record<Locale, PasswordMessages>} [i18n] - Custom error messages for different locales
  */
 export type PasswordOptions<IsRequired extends boolean = true> = {
-  required?: IsRequired
   min?: number
   max?: number
   uppercase?: boolean
@@ -191,7 +190,8 @@ const calculatePasswordStrength = (password: string): PasswordStrength => {
  * Creates a Zod schema for password validation with comprehensive security checks
  *
  * @template IsRequired - Whether the field is required (affects return type)
- * @param {PasswordOptions<IsRequired>} [options] - Configuration options for password validation
+ * @param {IsRequired} [required=false] - Whether the field is required
+ * @param {Omit<ValidatorOptions<IsRequired>, 'required'>} [options] - Configuration options for validation
  * @returns {PasswordSchema<IsRequired>} Zod schema for password validation
  *
  * @description
@@ -212,11 +212,18 @@ const calculatePasswordStrength = (password: string): PasswordStrength => {
  * @example
  * ```typescript
  * // Basic password validation
- * const basicSchema = password()
+ * const basicSchema = password() // optional by default
  * basicSchema.parse("MyPassword123!") // ✓ Valid
+ * basicSchema.parse(null) // ✓ Valid (optional)
+ *
+ * // Required validation
+ * const requiredSchema = parse("MyPassword123!") // ✓ Valid
+(true)
+ * requiredSchema.parse(null) // ✗ Invalid (required)
+ *
  *
  * // Strong password requirements
- * const strongSchema = password({
+ * const strongSchema = password(false, {
  *   min: 12,
  *   uppercase: true,
  *   lowercase: true,
@@ -226,7 +233,7 @@ const calculatePasswordStrength = (password: string): PasswordStrength => {
  * })
  *
  * // No common passwords
- * const secureSchema = password({
+ * const secureSchema = password(false, {
  *   noCommonWords: true,
  *   noRepeating: true,
  *   noSequential: true
@@ -236,7 +243,7 @@ const calculatePasswordStrength = (password: string): PasswordStrength => {
  * secureSchema.parse("abc123") // ✗ Invalid (sequential characters)
  *
  * // Custom requirements
- * const customSchema = password({
+ * const customSchema = password(false, {
  *   min: 8,
  *   includes: "@", // Must contain @
  *   excludes: ["admin", "user"], // Cannot contain these words
@@ -244,13 +251,12 @@ const calculatePasswordStrength = (password: string): PasswordStrength => {
  * })
  *
  * // Minimum strength requirement
- * const strengthSchema = password({ minStrength: "very-strong" })
+ * const strengthSchema = password(false, { minStrength: "very-strong" })
  * strengthSchema.parse("weak") // ✗ Invalid (insufficient strength)
  * strengthSchema.parse("MyVeryStr0ng!P@ssw0rd2024") // ✓ Valid
  *
  * // Optional with default
- * const optionalSchema = password({
- *   required: false,
+ * const optionalSchema = password(false, {
  *   defaultValue: null
  * })
  * ```
@@ -260,9 +266,8 @@ const calculatePasswordStrength = (password: string): PasswordStrength => {
  * @see {@link PasswordStrength} for strength level definitions
  * @see {@link calculatePasswordStrength} for strength calculation logic
  */
-export function password<IsRequired extends boolean = true>(options?: PasswordOptions<IsRequired>): PasswordSchema<IsRequired> {
+export function password<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<PasswordOptions<IsRequired>, 'required'>): PasswordSchema<IsRequired> {
   const {
-    required = true,
     min,
     max,
     uppercase,
@@ -281,8 +286,10 @@ export function password<IsRequired extends boolean = true>(options?: PasswordOp
     i18n,
   } = options ?? {}
 
+  const isRequired = required ?? false as IsRequired
+
   // Set appropriate default value based on required flag
-  const actualDefaultValue = defaultValue ?? (required ? "" : null)
+  const actualDefaultValue = defaultValue ?? (isRequired ? "" : null)
 
   // Helper function to get custom message or fallback to default i18n
   const getMessage = (key: keyof PasswordMessages, params?: Record<string, any>) => {
@@ -311,13 +318,13 @@ export function password<IsRequired extends boolean = true>(options?: PasswordOp
     return processed
   }
 
-  const baseSchema = required ? z.preprocess(preprocessFn, z.string()) : z.preprocess(preprocessFn, z.string().nullable())
+  const baseSchema = isRequired ? z.preprocess(preprocessFn, z.string()) : z.preprocess(preprocessFn, z.string().nullable())
 
   const schema = baseSchema.refine((val) => {
     if (val === null) return true
 
     // Required check
-    if (required && (val === "" || val === "null" || val === "undefined")) {
+    if (isRequired && (val === "" || val === "null" || val === "undefined")) {
       throw new z.ZodError([{ code: "custom", message: getMessage("required"), path: [] }])
     }
 

package/src/validators/common/text.ts

@@ -60,7 +60,6 @@ export type TextMessages = {
  * @property {Record<Locale, TextMessages>} [i18n] - Custom error messages for different locales
  */
 export type TextOptions<IsRequired extends boolean = true> = {
-  required?: IsRequired
   minLength?: number
   maxLength?: number
   startsWith?: string
@@ -108,17 +107,23 @@ export type TextSchema<IsRequired extends boolean> = IsRequired extends true ? Z
  *
  * @example
  * ```typescript
- * // Basic text validation
+ * // Basic text validation (optional by default)
  * const basicSchema = text()
  * basicSchema.parse("Hello World") // ✓ Valid
+ * basicSchema.parse(null) // ✓ Valid (optional)
+ *
+ * // Required text
+ * const requiredSchema = text(true)
+ * requiredSchema.parse("Hello") // ✓ Valid
+ * requiredSchema.parse(null) // ✗ Invalid (required)
  *
  * // Length constraints
- * const lengthSchema = text({ minLength: 3, maxLength: 50 })
+ * const lengthSchema = text(true, { minLength: 3, maxLength: 50 })
  * lengthSchema.parse("Hello") // ✓ Valid
  * lengthSchema.parse("Hi") // ✗ Invalid (too short)
  *
  * // Content validation
- * const contentSchema = text({
+ * const contentSchema = text(true, {
  *   startsWith: "Hello",
  *   endsWith: "!",
  *   includes: "World"
@@ -126,38 +131,37 @@ export type TextSchema<IsRequired extends boolean> = IsRequired extends true ? Z
  * contentSchema.parse("Hello World!") // ✓ Valid
  *
  * // Case transformation
- * const upperSchema = text({ casing: "upper" })
+ * const upperSchema = text(false, { casing: "upper" })
  * upperSchema.parse("hello") // ✓ Valid (converted to "HELLO")
  *
  * // Trim modes
- * const trimStartSchema = text({ trimMode: "trimStart" })
+ * const trimStartSchema = text(false, { trimMode: "trimStart" })
  * trimStartSchema.parse("  hello  ") // ✓ Valid (result: "hello  ")
  *
  * // Regex validation
- * const regexSchema = text({ regex: /^[a-zA-Z]+$/ })
+ * const regexSchema = text(true, { regex: /^[a-zA-Z]+$/ })
  * regexSchema.parse("hello") // ✓ Valid
  * regexSchema.parse("hello123") // ✗ Invalid
  *
  * // Not empty (rejects whitespace-only)
- * const notEmptySchema = text({ notEmpty: true })
+ * const notEmptySchema = text(true, { notEmpty: true })
  * notEmptySchema.parse("hello") // ✓ Valid
  * notEmptySchema.parse("   ") // ✗ Invalid
  *
  * // Optional with default
- * const optionalSchema = text({
- *   required: false,
- *   defaultValue: "default text"
- * })
+ * const optionalSchema = text(false, { defaultValue: "default text" })
  * ```
  *
  * @throws {z.ZodError} When validation fails with specific error messages
  * @see {@link TextOptions} for all available configuration options
  */
-export function text<IsRequired extends boolean = true>(options?: TextOptions<IsRequired>): TextSchema<IsRequired> {
-  const { required = true, minLength, maxLength, startsWith, endsWith, includes, excludes, regex, trimMode = "trim", casing = "none", transform, notEmpty, defaultValue, i18n } = options ?? {}
+export function text<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<TextOptions<IsRequired>, 'required'>): TextSchema<IsRequired> {
+  const { minLength, maxLength, startsWith, endsWith, includes, excludes, regex, trimMode = "trim", casing = "none", transform, notEmpty, defaultValue, i18n } = options ?? {}
+
+  const isRequired = required ?? false as IsRequired
 
   // Set appropriate default value based on required flag
-  const actualDefaultValue = defaultValue ?? (required ? "" : null)
+  const actualDefaultValue = defaultValue ?? (isRequired ? "" : null)
 
   // Helper function to get custom message or fallback to default i18n
   const getMessage = (key: keyof TextMessages, params?: Record<string, any>) => {
@@ -217,14 +221,14 @@ export function text<IsRequired extends boolean = true>(options?: TextOptions<Is
     return processed
   }
 
-  const baseSchema = required ? z.preprocess(preprocessFn, z.string()) : z.preprocess(preprocessFn, z.string().nullable())
+  const baseSchema = isRequired ? z.preprocess(preprocessFn, z.string()) : z.preprocess(preprocessFn, z.string().nullable())
 
   // Single refine with all validations for better performance
   const schema = baseSchema.refine((val) => {
     if (val === null) return true
 
     // Required check
-    if (required && (val === "" || val === "null" || val === "undefined")) {
+    if (isRequired && (val === "" || val === "null" || val === "undefined")) {
       throw new z.ZodError([{ code: "custom", message: getMessage("required"), path: [] }])
     }
 

package/src/validators/common/time.ts

@@ -92,7 +92,6 @@ export type TimeFormat =
  * @property {Record<Locale, TimeMessages>} [i18n] - Custom error messages for different locales
  */
 export type TimeOptions<IsRequired extends boolean = true> = {
-  required?: IsRequired
   format?: TimeFormat
   min?: string        // Minimum time (e.g., "09:00")
   max?: string        // Maximum time (e.g., "17:00")
@@ -284,7 +283,8 @@ const normalizeTime = (timeStr: string, format: TimeFormat): string | null => {
  * Creates a Zod schema for time validation with comprehensive options
  *
  * @template IsRequired - Whether the field is required (affects return type)
- * @param {TimeOptions<IsRequired>} [options] - Configuration options for time validation
+ * @param {IsRequired} [required=false] - Whether the field is required
+ * @param {Omit<ValidatorOptions<IsRequired>, 'required'>} [options] - Configuration options for validation
  * @returns {TimeSchema<IsRequired>} Zod schema for time validation
  *
  * @description
@@ -306,10 +306,17 @@ const normalizeTime = (timeStr: string, format: TimeFormat): string | null => {
  * // Basic time validation (24-hour format)
  * const basicSchema = time()
  * basicSchema.parse("14:30") // ✓ Valid
+ * basicSchema.parse(null) // ✓ Valid (optional)
+ *
+ * // Required validation
+ * const requiredSchema = parse("14:30") // ✓ Valid
+(true)
+ * requiredSchema.parse(null) // ✗ Invalid (required)
+ *
  * basicSchema.parse("2:30 PM") // ✗ Invalid (wrong format)
  *
  * // 12-hour format with AM/PM
- * const ampmSchema = time({ format: "hh:mm A" })
+ * const ampmSchema = time(false, { format: "hh:mm A" })
  * ampmSchema.parse("02:30 PM") // ✓ Valid
  * ampmSchema.parse("14:30") // ✗ Invalid (wrong format)
  *
@@ -325,7 +332,7 @@ const normalizeTime = (timeStr: string, format: TimeFormat): string | null => {
  * businessHours.parse("09:05") // ✗ Invalid (not 15-minute step)
  *
  * // Time range validation
- * const timeRangeSchema = time({
+ * const timeRangeSchema = time(false, {
  *   min: "09:00",
  *   max: "17:00"
  * })
@@ -340,7 +347,7 @@ const normalizeTime = (timeStr: string, format: TimeFormat): string | null => {
  * specificHours.parse("11:30") // ✗ Invalid (hour not allowed)
  *
  * // Whitelist specific times
- * const whitelistSchema = time({
+ * const whitelistSchema = time(false, {
  *   whitelist: ["09:00", "12:00", "17:00"],
  *   whitelistOnly: true
  * })
@@ -348,8 +355,7 @@ const normalizeTime = (timeStr: string, format: TimeFormat): string | null => {
  * whitelistSchema.parse("13:00") // ✗ Invalid (not in whitelist)
  *
  * // Optional with default
- * const optionalSchema = time({
- *   required: false,
+ * const optionalSchema = time(false, {
  *   defaultValue: "09:00"
  * })
  * optionalSchema.parse("") // ✓ Valid (returns "09:00")
@@ -359,9 +365,8 @@ const normalizeTime = (timeStr: string, format: TimeFormat): string | null => {
  * @see {@link TimeOptions} for all available configuration options
  * @see {@link TimeFormat} for supported time formats
  */
-export function time<IsRequired extends boolean = true>(options?: TimeOptions<IsRequired>): TimeSchema<IsRequired> {
+export function time<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<TimeOptions<IsRequired>, 'required'>): TimeSchema<IsRequired> {
   const {
-    required = true,
     format = "HH:mm",
     min,
     max,
@@ -382,8 +387,10 @@ export function time<IsRequired extends boolean = true>(options?: TimeOptions<Is
     i18n,
   } = options ?? {}
 
+  const isRequired = required ?? false as IsRequired
+
   // Set appropriate default value based on required flag
-  const actualDefaultValue = defaultValue ?? (required ? "" : null)
+  const actualDefaultValue = defaultValue ?? (isRequired ? "" : null)
 
   // Helper function to get custom message or fallback to default i18n
   const getMessage = (key: keyof TimeMessages, params?: Record<string, any>) => {
@@ -429,7 +436,7 @@ export function time<IsRequired extends boolean = true>(options?: TimeOptions<Is
         return ""
       }
       // If the field is optional and empty string not in whitelist, return default value
-      if (!required) {
+      if (!isRequired) {
         return actualDefaultValue
       }
       // If a field is required, return the default value (will be validated later)
@@ -456,18 +463,18 @@ export function time<IsRequired extends boolean = true>(options?: TimeOptions<Is
     return processed
   }
 
-  const baseSchema = required ? z.preprocess(preprocessFn, z.string()) : z.preprocess(preprocessFn, z.string().nullable())
+  const baseSchema = isRequired ? z.preprocess(preprocessFn, z.string()) : z.preprocess(preprocessFn, z.string().nullable())
 
   const schema = baseSchema.refine((val) => {
     if (val === null) return true
 
     // Required check
-    if (required && (val === "" || val === "null" || val === "undefined")) {
+    if (isRequired && (val === "" || val === "null" || val === "undefined")) {
       throw new z.ZodError([{ code: "custom", message: getMessage("required"), path: [] }])
     }
 
     if (val === null) return true
-    if (!required && val === "") return true
+    if (!isRequired && val === "") return true
 
     // Whitelist check
     if (whitelist && whitelist.length > 0) {

package/src/validators/common/url.ts

@@ -85,7 +85,6 @@ export type UrlMessages = {
  * @property {Record<Locale, UrlMessages>} [i18n] - Custom error messages for different locales
  */
 export type UrlOptions<IsRequired extends boolean = true> = {
-  required?: IsRequired
   min?: number
   max?: number
   includes?: string
@@ -121,7 +120,8 @@ export type UrlSchema<IsRequired extends boolean> = IsRequired extends true ? Zo
  * Creates a Zod schema for URL validation with comprehensive constraints
  *
  * @template IsRequired - Whether the field is required (affects return type)
- * @param {UrlOptions<IsRequired>} [options] - Configuration options for URL validation
+ * @param {IsRequired} [required=false] - Whether the field is required
+ * @param {Omit<ValidatorOptions<IsRequired>, 'required'>} [options] - Configuration options for validation
  * @returns {UrlSchema<IsRequired>} Zod schema for URL validation
  *
  * @description
@@ -145,43 +145,49 @@ export type UrlSchema<IsRequired extends boolean> = IsRequired extends true ? Zo
  * @example
  * ```typescript
  * // Basic URL validation
- * const basicSchema = url()
+ * const basicSchema = url() // optional by default
  * basicSchema.parse("https://example.com") // ✓ Valid
+ * basicSchema.parse(null) // ✓ Valid (optional)
+ *
+ * // Required validation
+ * const requiredSchema = parse("https://example.com") // ✓ Valid
+(true)
+ * requiredSchema.parse(null) // ✗ Invalid (required)
+ *
  *
  * // HTTPS only
- * const httpsSchema = url({ protocols: ["https"] })
+ * const httpsSchema = url(false, { protocols: ["https"] })
  * httpsSchema.parse("https://example.com") // ✓ Valid
  * httpsSchema.parse("http://example.com") // ✗ Invalid
  *
  * // Domain restriction
- * const domainSchema = url({
+ * const domainSchema = url(false, {
  *   allowedDomains: ["company.com", "trusted.org"]
  * })
  * domainSchema.parse("https://app.company.com") // ✓ Valid (subdomain)
  * domainSchema.parse("https://example.com") // ✗ Invalid
  *
  * // Block localhost
- * const noLocalhostSchema = url({ blockLocalhost: true })
+ * const noLocalhostSchema = url(false, { blockLocalhost: true })
  * noLocalhostSchema.parse("https://example.com") // ✓ Valid
  * noLocalhostSchema.parse("http://localhost:3000") // ✗ Invalid
  *
  * // API endpoints with path requirements
- * const apiSchema = url({
+ * const apiSchema = url(false, {
  *   pathStartsWith: "/api/",
  *   mustHaveQuery: true
  * })
  * apiSchema.parse("https://api.com/api/users?page=1") // ✓ Valid
  *
  * // Port restrictions
- * const portSchema = url({
+ * const portSchema = url(false, {
  *   allowedPorts: [80, 443, 8080]
  * })
  * portSchema.parse("https://example.com:443") // ✓ Valid
  * portSchema.parse("https://example.com:3000") // ✗ Invalid
  *
  * // Optional with default
- * const optionalSchema = url({
- *   required: false,
+ * const optionalSchema = url(false, {
  *   defaultValue: null
  * })
  * ```
@@ -189,9 +195,8 @@ export type UrlSchema<IsRequired extends boolean> = IsRequired extends true ? Zo
  * @throws {z.ZodError} When validation fails with specific error messages
  * @see {@link UrlOptions} for all available configuration options
  */
-export function url<IsRequired extends boolean = true>(options?: UrlOptions<IsRequired>): UrlSchema<IsRequired> {
+export function url<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<UrlOptions<IsRequired>, 'required'>): UrlSchema<IsRequired> {
   const {
-    required = true,
     min,
     max,
     includes,
@@ -214,7 +219,9 @@ export function url<IsRequired extends boolean = true>(options?: UrlOptions<IsRe
     i18n,
   } = options ?? {}
 
-  const actualDefaultValue = defaultValue ?? (required ? "" : null)
+  const isRequired = required ?? false as IsRequired
+
+  const actualDefaultValue = defaultValue ?? (isRequired ? "" : null)
 
   // Helper function to get custom message or fallback to default i18n
   const getMessage = (key: keyof UrlMessages, params?: Record<string, any>) => {
@@ -244,13 +251,13 @@ export function url<IsRequired extends boolean = true>(options?: UrlOptions<IsRe
     return processed
   }
 
-  const baseSchema = required ? z.preprocess(preprocessFn, z.string()) : z.preprocess(preprocessFn, z.string().nullable())
+  const baseSchema = isRequired ? z.preprocess(preprocessFn, z.string()) : z.preprocess(preprocessFn, z.string().nullable())
 
   const schema = baseSchema.refine((val) => {
     if (val === null) return true
 
     // Required check
-    if (required && (val === "" || val === "null" || val === "undefined")) {
+    if (isRequired && (val === "" || val === "null" || val === "undefined")) {
       throw new z.ZodError([{ code: "custom", message: getMessage("required"), path: [] }])
     }
 

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

@@ -36,7 +36,6 @@ export type BusinessIdMessages = {
  * @property {Record<Locale, BusinessIdMessages>} [i18n] - Custom error messages for different locales
  */
 export type BusinessIdOptions<IsRequired extends boolean = true> = {
-  required?: IsRequired
   transform?: (value: string) => string
   defaultValue?: IsRequired extends true ? string : string | null
   i18n?: Record<Locale, BusinessIdMessages>
@@ -148,23 +147,30 @@ const validateTaiwanBusinessId = (value: string): boolean => {
  * @example
  * ```typescript
  * // Basic business ID validation
- * const basicSchema = businessId()
+ * const basicSchema = businessId() // optional by default
  * basicSchema.parse("12345675") // ✓ Valid (if checksum correct)
+ * basicSchema.parse(null) // ✓ Valid (optional)
+ *
+ * // Required validation
+ * const requiredSchema = parse("12345675") // ✓ Valid (if checksum correct)
+(true)
+ * requiredSchema.parse(null) // ✗ Invalid (required)
+ *
  * basicSchema.parse("1234567") // ✗ Invalid (not 8 digits)
  *
  * // Optional business ID
- * const optionalSchema = businessId({ required: false })
+ * const optionalSchema = businessId(false)
  * optionalSchema.parse("") // ✓ Valid (returns null)
  * optionalSchema.parse("12345675") // ✓ Valid (if checksum correct)
  *
  * // With custom transformation
- * const transformSchema = businessId({
+ * const transformSchema = businessId(false, {
  *   transform: (value) => value.replace(/[^0-9]/g, '') // Remove non-digits
  * })
  * transformSchema.parse("1234-5675") // ✓ Valid (if checksum correct after cleaning)
  *
  * // With custom error messages
- * const customSchema = businessId({
+ * const customSchema = businessId(false, {
  *   i18n: {
  *     en: { invalid: "Please enter a valid Taiwan Business ID" },
  *     'zh-TW': { invalid: "請輸入有效的統一編號" }
@@ -176,16 +182,17 @@ const validateTaiwanBusinessId = (value: string): boolean => {
  * @see {@link BusinessIdOptions} for all available configuration options
  * @see {@link validateTaiwanBusinessId} for validation logic details
  */
-export function businessId<IsRequired extends boolean = true>(options?: BusinessIdOptions<IsRequired>): BusinessIdSchema<IsRequired> {
+export function businessId<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<BusinessIdOptions<IsRequired>, 'required'>): BusinessIdSchema<IsRequired> {
   const {
-    required = true,
     transform,
     defaultValue,
     i18n
   } = options ?? {}
 
+  const isRequired = required ?? false as IsRequired
+
   // Set appropriate default value based on required flag
-  const actualDefaultValue = defaultValue ?? (required ? "" : null)
+  const actualDefaultValue = defaultValue ?? (isRequired ? "" : null)
 
   // Helper function to get custom message or fallback to default i18n
   const getMessage = (key: keyof BusinessIdMessages, params?: Record<string, any>) => {
@@ -220,18 +227,18 @@ export function businessId<IsRequired extends boolean = true>(options?: Business
     return processed
   }
 
-  const baseSchema = required ? z.preprocess(preprocessFn, z.string()) : z.preprocess(preprocessFn, z.string().nullable())
+  const baseSchema = isRequired ? z.preprocess(preprocessFn, z.string()) : z.preprocess(preprocessFn, z.string().nullable())
 
   const schema = baseSchema.refine((val) => {
     if (val === null) return true
 
     // Required check
-    if (required && (val === "" || val === "null" || val === "undefined")) {
+    if (isRequired && (val === "" || val === "null" || val === "undefined")) {
       throw new z.ZodError([{ code: "custom", message: getMessage("required"), path: [] }])
     }
 
     if (val === null) return true
-    if (!required && val === "") return true
+    if (!isRequired && val === "") return true
 
     // Taiwan Business ID format validation (8 digits + checksum)
     if (!validateTaiwanBusinessId(val)) {