@hy_ong/zod-kit 0.0.4 → 0.0.6

package/src/validators/common/url.ts

@@ -0,0 +1,347 @@
+/**
+ * @fileoverview URL validator for Zod Kit
+ *
+ * Provides comprehensive URL validation with protocol filtering, domain control,
+ * port validation, path constraints, and localhost handling.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
+
+import { z, ZodNullable, ZodString } from "zod"
+import { t } from "../../i18n"
+import { getLocale, type Locale } from "../../config"
+
+/**
+ * Type definition for URL validation error messages
+ *
+ * @interface UrlMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when URL format is invalid
+ * @property {string} [min] - Message when URL is too short
+ * @property {string} [max] - Message when URL is too long
+ * @property {string} [includes] - Message when URL doesn't contain required string
+ * @property {string} [excludes] - Message when URL contains forbidden string
+ * @property {string} [protocol] - Message when protocol is not allowed
+ * @property {string} [domain] - Message when domain is not allowed
+ * @property {string} [domainBlacklist] - Message when domain is blacklisted
+ * @property {string} [port] - Message when port is not allowed
+ * @property {string} [pathStartsWith] - Message when path doesn't start with required string
+ * @property {string} [pathEndsWith] - Message when path doesn't end with required string
+ * @property {string} [hasQuery] - Message when query parameters are required
+ * @property {string} [noQuery] - Message when query parameters are forbidden
+ * @property {string} [hasFragment] - Message when fragment is required
+ * @property {string} [noFragment] - Message when fragment is forbidden
+ * @property {string} [localhost] - Message when localhost is forbidden
+ * @property {string} [noLocalhost] - Message when localhost is required
+ */
+export type UrlMessages = {
+  required?: string
+  invalid?: string
+  min?: string
+  max?: string
+  includes?: string
+  excludes?: string
+  protocol?: string
+  domain?: string
+  domainBlacklist?: string
+  port?: string
+  pathStartsWith?: string
+  pathEndsWith?: string
+  hasQuery?: string
+  noQuery?: string
+  hasFragment?: string
+  noFragment?: string
+  localhost?: string
+  noLocalhost?: string
+}
+
+/**
+ * Configuration options for URL validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface UrlOptions
+ * @property {IsRequired} [required=true] - Whether the field is required
+ * @property {number} [min] - Minimum length of URL
+ * @property {number} [max] - Maximum length of URL
+ * @property {string} [includes] - String that must be included in URL
+ * @property {string | string[]} [excludes] - String(s) that must not be included
+ * @property {string[]} [protocols] - Allowed protocols (e.g., ["https", "http"])
+ * @property {string[]} [allowedDomains] - Domains that are allowed
+ * @property {string[]} [blockedDomains] - Domains that are blocked
+ * @property {number[]} [allowedPorts] - Ports that are allowed
+ * @property {number[]} [blockedPorts] - Ports that are blocked
+ * @property {string} [pathStartsWith] - Path must start with this string
+ * @property {string} [pathEndsWith] - Path must end with this string
+ * @property {boolean} [mustHaveQuery] - Whether URL must have query parameters
+ * @property {boolean} [mustNotHaveQuery] - Whether URL must not have query parameters
+ * @property {boolean} [mustHaveFragment] - Whether URL must have fragment
+ * @property {boolean} [mustNotHaveFragment] - Whether URL must not have fragment
+ * @property {boolean} [allowLocalhost=true] - Whether to allow localhost URLs
+ * @property {boolean} [blockLocalhost] - Whether to explicitly block localhost URLs
+ * @property {Function} [transform] - Custom transformation function for URL strings
+ * @property {string | null} [defaultValue] - Default value when input is empty
+ * @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
+  excludes?: string | string[]
+  protocols?: string[]
+  allowedDomains?: string[]
+  blockedDomains?: string[]
+  allowedPorts?: number[]
+  blockedPorts?: number[]
+  pathStartsWith?: string
+  pathEndsWith?: string
+  mustHaveQuery?: boolean
+  mustNotHaveQuery?: boolean
+  mustHaveFragment?: boolean
+  mustNotHaveFragment?: boolean
+  allowLocalhost?: boolean
+  blockLocalhost?: boolean
+  transform?: (value: string) => string
+  defaultValue?: IsRequired extends true ? string : string | null
+  i18n?: Record<Locale, UrlMessages>
+}
+
+/**
+ * Type alias for URL validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef UrlSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
+export type UrlSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
+
+/**
+ * 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
+ * @returns {UrlSchema<IsRequired>} Zod schema for URL validation
+ *
+ * @description
+ * Creates a comprehensive URL validator with protocol filtering, domain control,
+ * port validation, path constraints, and localhost handling.
+ *
+ * Features:
+ * - RFC-compliant URL format validation
+ * - Protocol whitelist/blacklist (http, https, ftp, etc.)
+ * - Domain whitelist/blacklist with subdomain support
+ * - Port validation and filtering
+ * - Path prefix/suffix validation
+ * - Query parameter requirements
+ * - Fragment requirements
+ * - Localhost detection and control
+ * - Length validation
+ * - Content inclusion/exclusion
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ *
+ * @example
+ * ```typescript
+ * // Basic URL validation
+ * const basicSchema = url()
+ * basicSchema.parse("https://example.com") // ✓ Valid
+ *
+ * // HTTPS only
+ * const httpsSchema = url({ protocols: ["https"] })
+ * httpsSchema.parse("https://example.com") // ✓ Valid
+ * httpsSchema.parse("http://example.com") // ✗ Invalid
+ *
+ * // Domain restriction
+ * const domainSchema = url({
+ *   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 })
+ * noLocalhostSchema.parse("https://example.com") // ✓ Valid
+ * noLocalhostSchema.parse("http://localhost:3000") // ✗ Invalid
+ *
+ * // API endpoints with path requirements
+ * const apiSchema = url({
+ *   pathStartsWith: "/api/",
+ *   mustHaveQuery: true
+ * })
+ * apiSchema.parse("https://api.com/api/users?page=1") // ✓ Valid
+ *
+ * // Port restrictions
+ * const portSchema = url({
+ *   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,
+ *   defaultValue: null
+ * })
+ * ```
+ *
+ * @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> {
+  const {
+    required = true,
+    min,
+    max,
+    includes,
+    excludes,
+    protocols,
+    allowedDomains,
+    blockedDomains,
+    allowedPorts,
+    blockedPorts,
+    pathStartsWith,
+    pathEndsWith,
+    mustHaveQuery,
+    mustNotHaveQuery,
+    mustHaveFragment,
+    mustNotHaveFragment,
+    allowLocalhost = true,
+    blockLocalhost,
+    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 UrlMessages, 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.url.${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: [] }])
+    }
+
+    // URL format validation
+    let urlObj: URL
+    try {
+      urlObj = new URL(val)
+    } catch {
+      throw new z.ZodError([{ code: "custom", message: getMessage("invalid"), path: [] }])
+    }
+
+    // Length checks
+    if (val !== null && min !== undefined && val.length < min) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("min", { min }), path: [] }])
+    }
+    if (val !== null && max !== undefined && val.length > max) {
+      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: [] }])
+        }
+      }
+    }
+
+    // Protocol validation
+    if (protocols && !protocols.includes(urlObj.protocol.slice(0, -1))) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("protocol", { protocols: protocols.join(", ") }), path: [] }])
+    }
+
+    // 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: [] }])
+    }
+    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: [] }])
+    }
+
+    // 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: [] }])
+    }
+    if (blockedPorts && blockedPorts.includes(port)) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("port", { port }), path: [] }])
+    }
+
+    // Path validation
+    if (pathStartsWith && !urlObj.pathname.startsWith(pathStartsWith)) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("pathStartsWith", { path: pathStartsWith }), path: [] }])
+    }
+    if (pathEndsWith && !urlObj.pathname.endsWith(pathEndsWith)) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("pathEndsWith", { path: pathEndsWith }), path: [] }])
+    }
+
+    // Query validation
+    if (mustHaveQuery && !urlObj.search) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("hasQuery"), path: [] }])
+    }
+    if (mustNotHaveQuery && urlObj.search) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("noQuery"), path: [] }])
+    }
+
+    // Fragment validation
+    if (mustHaveFragment && !urlObj.hash) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("hasFragment"), path: [] }])
+    }
+    if (mustNotHaveFragment && urlObj.hash) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("noFragment"), path: [] }])
+    }
+
+    // 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: [] }])
+    }
+    if (!allowLocalhost && isLocalhost) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("localhost"), path: [] }])
+    }
+
+    return true
+  })
+
+  return schema as unknown as UrlSchema<IsRequired>
+}

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

@@ -0,0 +1,262 @@
+/**
+ * @fileoverview Taiwan Business ID (統一編號) validator for Zod Kit
+ *
+ * Provides validation for Taiwan Business Identification Numbers (統一編號) with
+ * support for both new (2023+) and legacy validation rules.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.0.5
+ */
+
+import { z, ZodNullable, ZodString } from "zod"
+import { t } from "../../i18n"
+import { getLocale, type Locale } from "../../config"
+
+/**
+ * Type definition for business ID validation error messages
+ *
+ * @interface BusinessIdMessages
+ * @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 = {
+  required?: string
+  invalid?: string
+}
+
+/**
+ * Configuration options for Taiwan business ID validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ *
+ * @interface BusinessIdOptions
+ * @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
+ */
+export type BusinessIdOptions<IsRequired extends boolean = true> = {
+  required?: IsRequired
+  transform?: (value: string) => string
+  defaultValue?: IsRequired extends true ? string : string | null
+  i18n?: Record<Locale, BusinessIdMessages>
+}
+
+/**
+ * Type alias for business ID validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @typedef BusinessIdSchema
+ * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ */
+export type BusinessIdSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
+
+/**
+ * Validates Taiwan Business Identification Number (統一編號)
+ *
+ * @param {string} value - The business ID to validate
+ * @returns {boolean} True if the business ID is valid
+ *
+ * @description
+ * Validates Taiwan Business ID using both new (2023+) and legacy validation rules.
+ * The validation includes format checking (8 digits) and checksum verification.
+ *
+ * Validation rules:
+ * 1. Must be exactly 8 digits
+ * 2. Weighted sum calculation using coefficients [1,2,1,2,1,2,4] for first 7 digits
+ * 3. New rules (2023+): Sum + 8th digit must be divisible by 5
+ * 4. Legacy rules: Sum + 8th digit must be divisible by 10
+ * 5. Special case: If 7th digit is 7, try alternative calculation with +1
+ *
+ * @example
+ * ```typescript
+ * validateTaiwanBusinessId("12345675") // true (if valid checksum)
+ * validateTaiwanBusinessId("1234567") // false (not 8 digits)
+ * validateTaiwanBusinessId("abcd1234") // false (not all digits)
+ * ```
+ */
+const validateTaiwanBusinessId = (value: string): boolean => {
+  // Must be exactly 8 digits
+  if (!/^\d{8}$/.test(value)) {
+    return false
+  }
+
+  const digits = value.split('').map(Number)
+
+  // Coefficients for the first 7 digits
+  const coefficients = [1, 2, 1, 2, 1, 2, 4]
+
+  // Calculate weighted sum for first 7 digits
+  let sum = 0
+  for (let i = 0; i < 7; i++) {
+    const product = digits[i] * coefficients[i]
+    // Add individual digits of the product (split if >= 10)
+    sum += Math.floor(product / 10) + (product % 10)
+  }
+
+  // Add the check digit (8th digit)
+  sum += digits[7]
+
+  // New rules (2023+): Valid if sum is divisible by 5
+  if (sum % 5 === 0) {
+    return true
+  }
+
+  // Fall back to old rules: Valid if sum is divisible by 10
+  if (sum % 10 === 0) {
+    return true
+  }
+
+  // Special case for old rules: if 7th digit is 7
+  if (digits[6] === 7) {
+    let altSum = 0
+    for (let i = 0; i < 7; i++) {
+      const product = digits[i] * coefficients[i]
+      altSum += Math.floor(product / 10) + (product % 10)
+    }
+    // Add 1 and check digit
+    altSum += 1 + digits[7]
+
+    // Check both new and old rules
+    if (altSum % 5 === 0 || altSum % 10 === 0) {
+      return true
+    }
+  }
+
+  return false
+}
+
+/**
+ * Creates a Zod schema for Taiwan Business ID validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @param {BusinessIdOptions<IsRequired>} [options] - Configuration options for business ID validation
+ * @returns {BusinessIdSchema<IsRequired>} Zod schema for business ID validation
+ *
+ * @description
+ * Creates a comprehensive Taiwan Business ID validator that validates the format
+ * and checksum according to Taiwan government specifications.
+ *
+ * Features:
+ * - 8-digit format validation
+ * - Checksum verification (supports both new 2023+ and legacy rules)
+ * - Automatic trimming and preprocessing
+ * - Custom transformation functions
+ * - Comprehensive internationalization
+ * - Optional field support
+ *
+ * @example
+ * ```typescript
+ * // Basic business ID validation
+ * const basicSchema = businessId()
+ * basicSchema.parse("12345675") // ✓ Valid (if checksum correct)
+ * basicSchema.parse("1234567") // ✗ Invalid (not 8 digits)
+ *
+ * // Optional business ID
+ * const optionalSchema = businessId({ required: false })
+ * optionalSchema.parse("") // ✓ Valid (returns null)
+ * optionalSchema.parse("12345675") // ✓ Valid (if checksum correct)
+ *
+ * // With custom transformation
+ * const transformSchema = businessId({
+ *   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({
+ *   i18n: {
+ *     en: { invalid: "Please enter a valid Taiwan Business ID" },
+ *     'zh-TW': { invalid: "請輸入有效的統一編號" }
+ *   }
+ * })
+ * ```
+ *
+ * @throws {z.ZodError} When validation fails with specific error messages
+ * @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> {
+  const {
+    required = 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 BusinessIdMessages, 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(`taiwan.businessId.${key}`, params)
+  }
+
+  // Preprocessing function
+  const preprocessFn = (val: unknown) => {
+    if (val === "" || val === null || val === undefined) {
+      return actualDefaultValue
+    }
+
+    let processed = String(val).trim()
+
+    // If after trimming we have an empty string and the field is optional, return null
+    if (processed === "" && !required) {
+      return null
+    }
+
+    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: [] }])
+    }
+
+    if (val === null) return true
+    if (!required && val === "") return true
+
+    // Taiwan Business ID format validation (8 digits + checksum)
+    if (!validateTaiwanBusinessId(val)) {
+      throw new z.ZodError([{ code: "custom", message: getMessage("invalid"), path: [] }])
+    }
+
+    return true
+  })
+
+  return schema as unknown as BusinessIdSchema<IsRequired>
+}
+
+/**
+ * Utility function exported for external use
+ *
+ * @description
+ * The validation function can be used independently for business ID validation
+ * without creating a full Zod schema.
+ *
+ * @example
+ * ```typescript
+ * import { validateTaiwanBusinessId } from './business-id'
+ *
+ * // Direct validation
+ * const isValid = validateTaiwanBusinessId("12345675") // boolean
+ * ```
+ */
+export { validateTaiwanBusinessId }