@hy_ong/zod-kit 0.0.2 → 0.0.5

package/src/validators/common/date.ts

@@ -0,0 +1,171 @@
+import { z, ZodNullable, ZodString } from "zod"
+import { t } from "../../i18n"
+import { getLocale, type Locale } from "../../config"
+import dayjs from "dayjs"
+import customParseFormat from "dayjs/plugin/customParseFormat"
+import isSameOrAfter from "dayjs/plugin/isSameOrAfter"
+import isSameOrBefore from "dayjs/plugin/isSameOrBefore"
+import isToday from "dayjs/plugin/isToday"
+import weekday from "dayjs/plugin/weekday"
+
+dayjs.extend(isSameOrAfter)
+dayjs.extend(isSameOrBefore)
+dayjs.extend(customParseFormat)
+dayjs.extend(isToday)
+dayjs.extend(weekday)
+
+export type DateMessages = {
+  required?: string
+  invalid?: string
+  format?: string
+  min?: string
+  max?: string
+  includes?: string
+  excludes?: string
+  past?: string
+  future?: string
+  today?: string
+  notToday?: string
+  weekday?: string
+  notWeekday?: string
+  weekend?: string
+  notWeekend?: string
+}
+
+export type DateOptions<IsRequired extends boolean = true> = {
+  required?: IsRequired
+  min?: string
+  max?: string
+  format?: string
+  includes?: string
+  excludes?: string | string[]
+  mustBePast?: boolean
+  mustBeFuture?: boolean
+  mustBeToday?: boolean
+  mustNotBeToday?: boolean
+  weekdaysOnly?: boolean
+  weekendsOnly?: boolean
+  transform?: (value: string) => string
+  defaultValue?: IsRequired extends true ? string : string | null
+  i18n?: Record<Locale, DateMessages>
+}
+
+export type DateSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
+
+export function date<IsRequired extends boolean = true>(options?: DateOptions<IsRequired>): DateSchema<IsRequired> {
+  const {
+    required = true,
+    min,
+    max,
+    format = "YYYY-MM-DD",
+    includes,
+    excludes,
+    mustBePast,
+    mustBeFuture,
+    mustBeToday,
+    mustNotBeToday,
+    weekdaysOnly,
+    weekendsOnly,
+    transform,
+    defaultValue = null,
+    i18n,
+  } = options ?? {}
+
+  const actualDefaultValue = defaultValue ?? (required ? "" : null)
+
+  // Helper function to get custom message or fallback to default i18n
+  const getMessage = (key: keyof DateMessages, params?: Record<string, any>) => {
+    if (i18n) {
+      const currentLocale = getLocale()
+      const customMessages = i18n[currentLocale]
+      if (customMessages && customMessages[key]) {
+        const template = customMessages[key]!
+        return template.replace(/\$\{(\w+)}/g, (_, k) => params?.[k] ?? "")
+      }
+    }
+    return t(`common.date.${key}`, params)
+  }
+
+  // Preprocessing function with transformations
+  const preprocessFn = (val: unknown) => {
+    if (val === "" || val === null || val === undefined) {
+      return actualDefaultValue
+    }
+
+    let processed = String(val).trim()
+
+    if (transform) {
+      processed = transform(processed)
+    }
+
+    return processed
+  }
+
+  const baseSchema = required ? 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")) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("required"), path: [] }])
+    }
+
+    // Format validation
+    if (val !== null && !dayjs(val, format, true).isValid()) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("format", { format }), path: [] }])
+    }
+
+    const dateObj = dayjs(val, format)
+
+    // Range checks
+    if (val !== null && min !== undefined && !dateObj.isSameOrAfter(dayjs(min, format))) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("min", { min }), path: [] }])
+    }
+    if (val !== null && max !== undefined && !dateObj.isSameOrBefore(dayjs(max, format))) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("max", { max }), path: [] }])
+    }
+
+    // String content checks
+    if (val !== null && includes !== undefined && !val.includes(includes)) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("includes", { includes }), path: [] }])
+    }
+    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: [] }])
+        }
+      }
+    }
+
+    // Time-based validations
+    const today = dayjs().startOf('day')
+    const targetDate = dateObj.startOf('day')
+
+    if (val !== null && mustBePast && !targetDate.isBefore(today)) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("past"), path: [] }])
+    }
+    if (val !== null && mustBeFuture && !targetDate.isAfter(today)) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("future"), path: [] }])
+    }
+    if (val !== null && mustBeToday && !targetDate.isSame(today)) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("today"), path: [] }])
+    }
+    if (val !== null && mustNotBeToday && targetDate.isSame(today)) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("notToday"), path: [] }])
+    }
+
+    // Weekday/weekend validations
+    if (val !== null && weekdaysOnly && (dateObj.day() === 0 || dateObj.day() === 6)) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("weekday"), path: [] }])
+    }
+    if (val !== null && weekendsOnly && dateObj.day() !== 0 && dateObj.day() !== 6) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("weekend"), path: [] }])
+    }
+
+    return true
+  })
+
+  return schema as unknown as DateSchema<IsRequired>
+}

package/src/validators/common/email.ts

@@ -0,0 +1,200 @@
+import { z, ZodNullable, ZodString } from "zod"
+import { t } from "../../i18n"
+import { getLocale, type Locale } from "../../config"
+
+export type EmailMessages = {
+  required?: string
+  invalid?: string
+  minLength?: string
+  maxLength?: string
+  includes?: string
+  domain?: string
+  domainBlacklist?: string
+  businessOnly?: string
+  noDisposable?: string
+}
+
+export type EmailOptions<IsRequired extends boolean = true> = {
+  required?: IsRequired
+  domain?: string | string[]
+  domainBlacklist?: string[]
+  minLength?: number
+  maxLength?: number
+  includes?: string
+  excludes?: string | string[]
+  allowSubdomains?: boolean
+  businessOnly?: boolean
+  noDisposable?: boolean
+  lowercase?: boolean
+  transform?: (value: string) => string
+  defaultValue?: IsRequired extends true ? string : string | null
+  i18n?: Record<Locale, EmailMessages>
+}
+
+export type EmailSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
+
+export function email<IsRequired extends boolean = true>(options?: EmailOptions<IsRequired>): EmailSchema<IsRequired> {
+  const {
+    required = true,
+    domain,
+    domainBlacklist,
+    minLength,
+    maxLength,
+    includes,
+    excludes,
+    allowSubdomains = true,
+    businessOnly = false,
+    noDisposable = false,
+    lowercase = true,
+    transform,
+    defaultValue,
+    i18n,
+  } = options ?? {}
+
+  // Helper function to get custom message or fallback to default i18n
+  const getMessage = (key: keyof EmailMessages, params?: Record<string, any>) => {
+    if (i18n) {
+      const currentLocale = getLocale()
+      const customMessages = i18n[currentLocale]
+      if (customMessages && customMessages[key]) {
+        const template = customMessages[key]!
+        return template.replace(/\$\{(\w+)}/g, (_, k) => params?.[k] ?? "")
+      }
+    }
+    return t(`common.email.${key}`, params)
+  }
+
+  // Common disposable email domains
+  const disposableDomains = ["10minutemail.com", "tempmail.org", "guerrillamail.com", "mailinator.com", "yopmail.com", "temp-mail.org", "throwaway.email", "getnada.com", "maildrop.cc"]
+
+  // Common business email patterns (not free providers)
+  const freeEmailDomains = ["gmail.com", "yahoo.com", "hotmail.com", "outlook.com", "icloud.com", "aol.com", "protonmail.com", "zoho.com"]
+
+  const actualDefaultValue = defaultValue ?? null
+
+  const baseSchema = z.preprocess(
+    (val) => {
+      if (val === "" || val === null || val === undefined) {
+        return actualDefaultValue
+      }
+
+      let processed = String(val).trim()
+
+      if (lowercase) {
+        processed = processed.toLowerCase()
+      }
+
+      if (transform) {
+        processed = transform(processed)
+      }
+
+      return processed
+    },
+    z.union([z.string().email(), z.null()])
+  )
+
+  const schema = baseSchema.refine((val) => {
+    // Required check first
+    if (required && val === null) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("required"), path: [] }])
+    }
+
+    if (val === null) return true
+
+    // Invalid email check
+    if (typeof val !== "string") {
+      throw new z.ZodError([{ code: "custom", message: getMessage("invalid"), path: [] }])
+    }
+
+    // Length checks
+    if (minLength !== undefined && val.length < minLength) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("minLength", { minLength }), path: [] }])
+    }
+    if (maxLength !== undefined && val.length > maxLength) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("maxLength", { maxLength }), path: [] }])
+    }
+
+    // Content checks
+    if (includes !== undefined && !val.includes(includes)) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("includes", { includes }), path: [] }])
+    }
+
+    if (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("includes", { includes: exclude }), path: [] }])
+        }
+      }
+    }
+
+    // Extract domain from email
+    const emailDomain = val.split("@")[1]?.toLowerCase()
+    if (!emailDomain) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("invalid"), path: [] }])
+    }
+
+    // Business email check (should come before domain validation)
+    if (businessOnly) {
+      const isFreeProvider = freeEmailDomains.some((freeDomain) => {
+        if (allowSubdomains) {
+          return emailDomain === freeDomain || emailDomain.endsWith("." + freeDomain)
+        }
+        return emailDomain === freeDomain
+      })
+
+      if (isFreeProvider) {
+        throw new z.ZodError([{ code: "custom", message: getMessage("businessOnly"), path: [] }])
+      }
+    }
+
+    // Domain blacklist
+    if (domainBlacklist && domainBlacklist.length > 0) {
+      const isBlacklisted = domainBlacklist.some((blacklistedDomain) => {
+        const lowerDomain = blacklistedDomain.toLowerCase()
+        if (allowSubdomains) {
+          return emailDomain === lowerDomain || emailDomain.endsWith("." + lowerDomain)
+        }
+        return emailDomain === lowerDomain
+      })
+
+      if (isBlacklisted) {
+        throw new z.ZodError([{ code: "custom", message: getMessage("domainBlacklist", { domain: emailDomain }), path: [] }])
+      }
+    }
+
+    // Domain validation
+    if (domain !== undefined) {
+      const allowedDomains = Array.isArray(domain) ? domain : [domain]
+      const isAllowed = allowedDomains.some((allowedDomain) => {
+        const lowerDomain = allowedDomain.toLowerCase()
+        if (allowSubdomains) {
+          return emailDomain === lowerDomain || emailDomain.endsWith("." + lowerDomain)
+        }
+        return emailDomain === lowerDomain
+      })
+
+      if (!isAllowed) {
+        throw new z.ZodError([{ code: "custom", message: getMessage("domain", { domain: Array.isArray(domain) ? domain.join(", ") : domain }), path: [] }])
+      }
+    }
+
+    // Disposable email check
+    if (noDisposable) {
+      const isDisposable = disposableDomains.some((disposableDomain) => {
+        if (allowSubdomains) {
+          return emailDomain === disposableDomain || emailDomain.endsWith("." + disposableDomain)
+        }
+        return emailDomain === disposableDomain
+      })
+
+      if (isDisposable) {
+        throw new z.ZodError([{ code: "custom", message: getMessage("noDisposable"), path: [] }])
+      }
+    }
+
+    return true
+  })
+
+  return schema as unknown as EmailSchema<IsRequired>
+}

package/src/validators/common/id.ts

@@ -0,0 +1,259 @@
+import { z, ZodNullable, ZodString } from "zod"
+import { t } from "../../i18n"
+import { getLocale, type Locale } from "../../config"
+
+export type IdMessages = {
+  required?: string
+  invalid?: string
+  minLength?: string
+  maxLength?: string
+  numeric?: string
+  uuid?: string
+  objectId?: string
+  nanoid?: string
+  snowflake?: string
+  cuid?: string
+  ulid?: string
+  shortid?: string
+  customFormat?: string
+  includes?: string
+  excludes?: string
+  startsWith?: string
+  endsWith?: string
+}
+
+export type IdType =
+  | "numeric" // 純數字 ID (1, 123, 999999)
+  | "uuid" // UUID v4 格式
+  | "objectId" // MongoDB ObjectId (24位16進制)
+  | "nanoid" // Nano ID
+  | "snowflake" // Twitter Snowflake (19位數字)
+  | "cuid" // CUID 格式
+  | "ulid" // ULID 格式
+  | "shortid" // ShortId 格式
+  | "auto" // 自動檢測格式
+
+export type IdOptions<IsRequired extends boolean = true> = {
+  required?: IsRequired
+  type?: IdType
+  minLength?: number
+  maxLength?: number
+  allowedTypes?: IdType[]
+  customRegex?: RegExp
+  includes?: string
+  excludes?: string | string[]
+  startsWith?: string
+  endsWith?: string
+  caseSensitive?: boolean
+  transform?: (value: string) => string
+  defaultValue?: IsRequired extends true ? string : string | null
+  i18n?: Record<Locale, IdMessages>
+}
+
+export type IdSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
+
+// ID 格式的正則表達式
+const ID_PATTERNS = {
+  numeric: /^\d+$/,
+  uuid: /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
+  objectId: /^[0-9a-f]{24}$/i,
+  nanoid: /^[A-Za-z0-9_-]{21}$/,
+  snowflake: /^\d{19}$/,
+  cuid: /^c[a-z0-9]{24}$/,
+  ulid: /^[0-9A-HJKMNP-TV-Z]{26}$/,
+  shortid: /^[A-Za-z0-9_-]{7,14}$/,
+} as const
+
+// 檢測 ID 類型（按照特異性排序，避免誤判）
+const detectIdType = (value: string): IdType | null => {
+  // 按優先順序檢查（從最具體到最通用）
+  const orderedTypes: Array<[IdType, RegExp]> = [
+    ["uuid", ID_PATTERNS.uuid],
+    ["objectId", ID_PATTERNS.objectId],
+    ["snowflake", ID_PATTERNS.snowflake],
+    ["cuid", ID_PATTERNS.cuid],
+    ["ulid", ID_PATTERNS.ulid],
+    ["nanoid", ID_PATTERNS.nanoid],
+    ["numeric", ID_PATTERNS.numeric],
+    ["shortid", ID_PATTERNS.shortid], // 放最後，因為最通用
+  ]
+
+  for (const [type, pattern] of orderedTypes) {
+    if (pattern.test(value)) {
+      return type
+    }
+  }
+  return null
+}
+
+// 驗證特定 ID 類型
+const validateIdType = (value: string, type: IdType): boolean => {
+  if (type === "auto") {
+    return detectIdType(value) !== null
+  }
+  const pattern = ID_PATTERNS[type as keyof typeof ID_PATTERNS]
+  return pattern ? pattern.test(value) : false
+}
+
+export function id<IsRequired extends boolean = true>(options?: IdOptions<IsRequired>): IdSchema<IsRequired> {
+  const {
+    required = true,
+    type = "auto",
+    minLength,
+    maxLength,
+    allowedTypes,
+    customRegex,
+    includes,
+    excludes,
+    startsWith,
+    endsWith,
+    caseSensitive = true,
+    transform,
+    defaultValue,
+    i18n,
+  } = options ?? {}
+
+  // Set appropriate default value based on required flag
+  const actualDefaultValue = defaultValue ?? (required ? "" : null)
+
+  // Helper function to get custom message or fallback to default i18n
+  const getMessage = (key: keyof IdMessages, params?: Record<string, any>) => {
+    if (i18n) {
+      const currentLocale = getLocale()
+      const customMessages = i18n[currentLocale]
+      if (customMessages && customMessages[key]) {
+        const template = customMessages[key]!
+        return template.replace(/\$\{(\w+)}/g, (_, k) => params?.[k] ?? "")
+      }
+    }
+    return t(`common.id.${key}`, params)
+  }
+
+  // Preprocessing function
+  const preprocessFn = (val: unknown) => {
+    if (val === "" || val === null || val === undefined) {
+      return actualDefaultValue
+    }
+
+    let processed = String(val)
+
+    if (transform) {
+      processed = transform(processed)
+    }
+
+    return processed
+  }
+
+  const baseSchema = required ? 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")) {
+        throw new z.ZodError([{ code: "custom", message: getMessage("required"), path: [] }])
+      }
+
+      // Create comparison value for case-insensitive checks
+      const comparisonVal = !caseSensitive ? val.toLowerCase() : val
+
+      // Length checks
+      if (val !== null && minLength !== undefined && val.length < minLength) {
+        throw new z.ZodError([{ code: "custom", message: getMessage("minLength", { minLength }), path: [] }])
+      }
+      if (val !== null && maxLength !== undefined && val.length > maxLength) {
+        throw new z.ZodError([{ code: "custom", message: getMessage("maxLength", { maxLength }), path: [] }])
+      }
+
+      // Check if we have content-based validations that override format checking
+      const hasContentValidations = customRegex !== undefined || startsWith !== undefined || endsWith !== undefined || includes !== undefined || excludes !== undefined
+
+      // 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: [] }])
+        }
+      } else if (val !== null && !hasContentValidations) {
+        // ID type validation (only if no custom regex or content validations)
+        let isValidId: boolean
+
+        if (allowedTypes && allowedTypes.length > 0) {
+          // Check if ID matches any of the allowed types
+          isValidId = allowedTypes.some((allowedType) => validateIdType(val, allowedType))
+          if (!isValidId) {
+            const typeNames = allowedTypes.join(", ")
+            throw new z.ZodError([{ code: "custom", message: getMessage("invalid") + ` (allowed types: ${typeNames})`, path: [] }])
+          }
+        } else if (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: [] }])
+          }
+        } 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: [] }])
+          }
+        }
+      } else if (val !== null && hasContentValidations && 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))
+          if (!isValidType) {
+            const typeNames = allowedTypes.join(", ")
+            throw new z.ZodError([{ code: "custom", message: getMessage("invalid") + ` (allowed types: ${typeNames})`, path: [] }])
+          }
+        } else {
+          if (!validateIdType(val, type)) {
+            throw new z.ZodError([{ code: "custom", message: getMessage(type as keyof IdMessages) || getMessage("invalid"), path: [] }])
+          }
+        }
+      }
+
+      // String content checks (using comparisonVal for case sensitivity)
+      const searchStartsWith = !caseSensitive && startsWith ? startsWith.toLowerCase() : startsWith
+      const searchEndsWith = !caseSensitive && endsWith ? endsWith.toLowerCase() : endsWith
+      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: [] }])
+      }
+      if (val !== null && endsWith !== undefined && !comparisonVal.endsWith(searchEndsWith!)) {
+        throw new z.ZodError([{ code: "custom", message: getMessage("endsWith", { endsWith }), path: [] }])
+      }
+      if (val !== null && includes !== undefined && !comparisonVal.includes(searchIncludes!)) {
+        throw new z.ZodError([{ code: "custom", message: getMessage("includes", { includes }), path: [] }])
+      }
+      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: [] }])
+          }
+        }
+      }
+
+      return true
+    })
+    .transform((val) => {
+      if (val === null) return val
+
+      // Handle case transformations
+      const shouldPreserveCase = type === "uuid" || type === "objectId"
+
+      if (!caseSensitive && !shouldPreserveCase) {
+        return val.toLowerCase()
+      }
+
+      return val // preserve the original case for UUID/ObjectId or when case-sensitive
+    })
+
+  return schema as unknown as IdSchema<IsRequired>
+}
+
+// Export utility functions for external use
+export { detectIdType, validateIdType, ID_PATTERNS }