@hy_ong/zod-kit 0.2.8 → 0.2.9

package/src/validators/common/url.ts

@@ -116,6 +116,81 @@ export type UrlOptions<IsRequired extends boolean = true> = {
  */
 export type UrlSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
 
+const getNormalizedHostname = (hostname: string): string => hostname.toLowerCase().replace(/^\[(.*)]$/, "$1")
+
+const parseIPv4 = (hostname: string): number[] | null => {
+  const parts = hostname.split(".")
+  if (parts.length !== 4) return null
+
+  const octets = parts.map((part) => {
+    if (!/^\d+$/.test(part)) return null
+    const value = Number(part)
+    return Number.isInteger(value) && value >= 0 && value <= 255 ? value : null
+  })
+
+  return octets.every((part) => part !== null) ? octets as number[] : null
+}
+
+const isLocalIPv4 = ([first, second]: number[]): boolean => (
+  first === 0 ||
+  first === 10 ||
+  first === 127 ||
+  (first === 169 && second === 254) ||
+  (first === 172 && second >= 16 && second <= 31) ||
+  (first === 192 && second === 168)
+)
+
+const parseHextet = (value: string): number | null => {
+  if (!/^[0-9a-f]{1,4}$/i.test(value)) return null
+
+  const parsed = Number.parseInt(value, 16)
+  return Number.isInteger(parsed) && parsed >= 0 && parsed <= 0xffff ? parsed : null
+}
+
+const parseIPv4MappedIPv6 = (hostname: string): number[] | null => {
+  if (!hostname.startsWith("::ffff:")) return null
+
+  const mappedValue = hostname.slice("::ffff:".length)
+  const dottedIPv4 = parseIPv4(mappedValue)
+  if (dottedIPv4) return dottedIPv4
+
+  const hextets = mappedValue.split(":")
+  if (hextets.length !== 2) return null
+
+  const high = parseHextet(hextets[0])
+  const low = parseHextet(hextets[1])
+  if (high === null || low === null) return null
+
+  return [(high >> 8) & 0xff, high & 0xff, (low >> 8) & 0xff, low & 0xff]
+}
+
+const isLocalNetworkHostname = (hostname: string): boolean => {
+  const normalizedHostname = getNormalizedHostname(hostname)
+
+  if (normalizedHostname === "localhost") return true
+
+  const ipv4 = parseIPv4(normalizedHostname)
+  if (ipv4) {
+    return isLocalIPv4(ipv4)
+  }
+
+  if (!normalizedHostname.includes(":")) return false
+
+  const mappedIPv4 = parseIPv4MappedIPv6(normalizedHostname)
+  if (mappedIPv4) return isLocalIPv4(mappedIPv4)
+
+  const firstHextet = parseHextet(normalizedHostname.split(":")[0])
+
+  return (
+    normalizedHostname === "::" ||
+    normalizedHostname === "::1" ||
+    (firstHextet !== null && (
+      (firstHextet & 0xfe00) === 0xfc00 ||
+      (firstHextet & 0xffc0) === 0xfe80
+    ))
+  )
+}
+
 /**
  * Creates a Zod schema for URL validation with comprehensive constraints
  *
@@ -356,7 +431,7 @@ export function url<IsRequired extends boolean = false>(required?: IsRequired, o
     }
 
     // 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])\./)
+    const isLocalhost = isLocalNetworkHostname(hostname)
     if (blockLocalhost && isLocalhost) {
       ctx.addIssue({ code: "custom", message: getMessage("noLocalhost") })
       return

package/src/validators/taiwan/tel.ts

@@ -1,8 +1,8 @@
 /**
- * @fileoverview Taiwan Landline Telephone Number validator for Zod Kit
+ * @fileoverview Taiwan Telephone Number validator for Zod Kit
  *
- * Provides validation for Taiwan landline telephone numbers according to the
- * official 2024 telecom numbering plan with comprehensive area code support.
+ * Provides validation for Taiwan telephone numbers according to the official
+ * 2024 telecom numbering plan with area code and service code support.
  *
  * @author Ong Hoe Yuan
  * @version 0.0.5
@@ -27,19 +27,21 @@ export type TwTelMessages = {
 }
 
 /**
- * Configuration options for Taiwan landline telephone validation
+ * Configuration options for Taiwan telephone validation
  *
  * @template IsRequired - Whether the field is required (affects return type)
  *
  * @interface TwTelOptions
  * @property {IsRequired} [required=true] - Whether the field is required
  * @property {string[]} [whitelist] - Array of specific telephone numbers that are always allowed
+ * @property {boolean} [allowITFS=false] - Whether to allow 008 international toll-free numbers
  * @property {Function} [transform] - Custom transformation function for telephone number
  * @property {string | null} [defaultValue] - Default value when input is empty
  * @property {Record<Locale, TwTelMessages>} [i18n] - Custom error messages for different locales
  */
 export type TwTelOptions<IsRequired extends boolean = true> = {
   whitelist?: string[]
+  allowITFS?: boolean
   transform?: (value: string) => string
   defaultValue?: IsRequired extends true ? string : string | null
   i18n?: Partial<Record<Locale, Partial<TwTelMessages>>>
@@ -54,16 +56,39 @@ export type TwTelOptions<IsRequired extends boolean = true> = {
  */
 export type TwTelSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
 
+export type ValidateTaiwanTelOptions = {
+  allowITFS?: boolean
+}
+
+const normalizeTaiwanTel = (value: string): string => value.replace(/[-\s]/g, "")
+
+/**
+ * Validates Taiwan-dialed international toll-free number format.
+ *
+ * Supported formats:
+ * - 00800 + 8-digit Global Subscriber Number (UIFN)
+ * - 00801~00809 + 1-12 digit carrier-defined subscriber number (ITFS)
+ */
+const validateTaiwanInternationalTollFree = (value: string): boolean => {
+  const cleanValue = normalizeTaiwanTel(value)
+
+  if (/^00800\d{8}$/.test(cleanValue)) {
+    return true
+  }
+
+  return /^0080[1-9]\d{1,12}$/.test(cleanValue)
+}
+
 /**
- * Validates Taiwan landline telephone number format (Official 2024 rules)
+ * Validates Taiwan telephone number format (Official 2024 rules)
  *
  * @param {string} value - The telephone number to validate
+ * @param {ValidateTaiwanTelOptions} [options] - Optional validation settings
  * @returns {boolean} True if the telephone number is valid
  *
  * @description
- * Validates Taiwan landline telephone numbers according to the official 2024
- * telecom numbering plan. Supports all Taiwan area codes and their specific
- * number patterns.
+ * Validates Taiwan telephone numbers according to the official 2024 telecom
+ * numbering plan. Supports Taiwan area codes and selected service codes.
  *
  * Supported area codes and formats:
  * - 02: Taipei, New Taipei, Keelung - 8 digits
@@ -76,8 +101,10 @@ export type TwTelSchema<IsRequired extends boolean> = IsRequired extends true ?
  * - 07: Kaohsiung - 7-8 digits
  * - 08: Pingtung - 7 digits
  * - 070: VoIP / Internet Telephony (網路電話) - 8 digits (11 total)
- * - 0800: Toll-free - 6 digits
- * - 0809: Toll-free - 6 digits
+ * - 0800: Domestic recipient-paid/toll-free - 6 digits
+ * - 0809: Domestic recipient-paid/toll-free - 6 digits
+ * - 00800: Universal International Freephone Number (UIFN) when allowITFS is true
+ * - 00801~00809: International Toll-Free Service (ITFS) when allowITFS is true
  * - 082: Kinmen - 6 digits
  * - 0836: Matsu - 5-6 digits
  * - 089: Taitung - 6 digits
@@ -89,9 +116,12 @@ export type TwTelSchema<IsRequired extends boolean> = IsRequired extends true ?
  * validateTaiwanTel("037234567") // true (Miaoli area)
  * validateTaiwanTel("082234567") // true (Kinmen area)
  * validateTaiwanTel("02-2345-6789") // true (with separators)
+ * validateTaiwanTel("00801-852-747", { allowITFS: true }) // true (ITFS)
  * ```
  */
-const validateTaiwanTel = (value: string): boolean => {
+const validateTaiwanTel = (value: string, options: ValidateTaiwanTelOptions = {}): boolean => {
+  const { allowITFS = false } = options
+
   // Official Taiwan landline formats according to telecom numbering plan:
   // 02: Taipei, New Taipei, Keelung - 8 digits
   // 03: Taoyuan, Hsinchu, Yilan, Hualien - 7-8 digits
@@ -103,13 +133,17 @@ const validateTaiwanTel = (value: string): boolean => {
   // 07: Kaohsiung - 7-8 digits
   // 08: Pingtung - 7 digits
   // 070: VoIP / Internet Telephony (網路電話) - 8 digits (11 total)
-  // 0800/0809: Toll-free - 6 digits
+  // 0800/0809: Domestic recipient-paid/toll-free - 6 digits
   // 082: Kinmen - 6 digits
   // 0836: Matsu - 5-6 digits
   // 089: Taitung - 6 digits
 
   // Remove common separators for validation
-  const cleanValue = value.replace(/[-\s]/g, "")
+  const cleanValue = normalizeTaiwanTel(value)
+
+  if (allowITFS && validateTaiwanInternationalTollFree(cleanValue)) {
+    return true
+  }
 
   // Basic format: starts with 0, then area code, then number
   if (!/^0\d{7,10}$/.test(cleanValue)) {
@@ -119,7 +153,7 @@ const validateTaiwanTel = (value: string): boolean => {
   // Check 4-digit area codes first
   const areaCode4 = cleanValue.substring(0, 4)
   if (areaCode4 === "0800" || areaCode4 === "0809") {
-    // Toll-free: 0800/0809 + 6 digits, total 10 digits
+    // Domestic recipient-paid/toll-free: 0800/0809 + 6 digits, total 10 digits
     return cleanValue.length === 10 && /^080[09]\d{6}$/.test(cleanValue)
   }
   if (areaCode4 === "0836") {
@@ -206,7 +240,7 @@ const validateTaiwanTel = (value: string): boolean => {
 }
 
 /**
- * Creates a Zod schema for Taiwan landline telephone number validation
+ * Creates a Zod schema for Taiwan telephone number validation
  *
  * @template IsRequired - Whether the field is required (affects return type)
  * @param {IsRequired} [required=false] - Whether the field is required
@@ -214,11 +248,13 @@ const validateTaiwanTel = (value: string): boolean => {
  * @returns {TwTelSchema<IsRequired>} Zod schema for telephone number validation
  *
  * @description
- * Creates a comprehensive Taiwan landline telephone number validator with support for
- * all Taiwan area codes according to the official 2024 telecom numbering plan.
+ * Creates a comprehensive Taiwan telephone number validator with support for
+ * Taiwan area codes and selected service codes according to the official 2024
+ * telecom numbering plan.
  *
  * Features:
  * - Complete Taiwan area code support (02, 03, 037, 04, 049, 05, 06, 07, 08, 082, 0826, 0836, 089)
+ * - Optional 008 international toll-free support (UIFN/ITFS)
  * - Automatic separator handling (hyphens and spaces)
  * - Area-specific number length and pattern validation
  * - Whitelist functionality for specific allowed numbers
@@ -262,6 +298,13 @@ const validateTaiwanTel = (value: string): boolean => {
  * transformSchema.parse("02-2345-6789") // ✓ Valid (separators removed)
  * transformSchema.parse("02 2345 6789") // ✓ Valid (spaces removed)
  *
+ * // With Taiwan-dialed international toll-free support
+ * const itfsSchema = twTel(false, {
+ *   allowITFS: true
+ * })
+ * itfsSchema.parse("00800-2468-1668") // ✓ Valid (UIFN)
+ * itfsSchema.parse("00801-852-747") // ✓ Valid (ITFS)
+ *
  * // With custom error messages
  * const customSchema = twTel(false, {
  *   i18n: {
@@ -276,7 +319,7 @@ const validateTaiwanTel = (value: string): boolean => {
  * @see {@link validateTaiwanTel} for validation logic details
  */
 export function twTel<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<TwTelOptions<IsRequired>, 'required'>): TwTelSchema<IsRequired> {
-  const { whitelist, transform, defaultValue, i18n } = options ?? {}
+  const { whitelist, allowITFS = false, transform, defaultValue, i18n } = options ?? {}
 
   const isRequired = required ?? false as IsRequired
 
@@ -345,7 +388,7 @@ export function twTel<IsRequired extends boolean = false>(required?: IsRequired,
     }
 
     // Taiwan telephone format validation
-    if (!validateTaiwanTel(val)) {
+    if (!validateTaiwanTel(val, { allowITFS })) {
       ctx.addIssue({ code: "custom", message: getMessage("invalid") })
       return
     }
@@ -369,4 +412,4 @@ export function twTel<IsRequired extends boolean = false>(required?: IsRequired,
  * const isValid = validateTaiwanTel("0223456789") // boolean
  * ```
  */
-export { validateTaiwanTel }
+export { validateTaiwanTel, validateTaiwanInternationalTollFree }

package/tests/common/file.test.ts

@@ -49,6 +49,26 @@ describe("file(true) features", () => {
       expect(schema.parse(undefined)).toBe(null)
       expect(schema.parse("")).toBe(null)
     })
+
+    it("should not throw while creating a schema when File is unavailable", () => {
+      const originalFile = globalThis.File
+
+      try {
+        Object.defineProperty(globalThis, "File", {
+          value: undefined,
+          configurable: true,
+        })
+
+        const schema = file(false)
+        expect(schema.parse(null)).toBe(null)
+        expect(() => schema.parse("not a file")).toThrow("Invalid file")
+      } finally {
+        Object.defineProperty(globalThis, "File", {
+          value: originalFile,
+          configurable: true,
+        })
+      }
+    })
   })
 
   describe("file size validation", () => {

package/tests/common/url.test.ts

@@ -267,6 +267,15 @@ describe("url", () => {
       expect(() => schema.parse("http://192.168.1.1")).toThrow()
     })
 
+    it("should block all loopback and unspecified hosts when blockLocalhost is true", () => {
+      const schema = url(true, { blockLocalhost: true })
+
+      expect(() => schema.parse("http://127.0.0.2")).toThrow()
+      expect(() => schema.parse("http://0.0.0.0")).toThrow()
+      expect(() => schema.parse("http://[::1]")).toThrow()
+      expect(() => schema.parse("http://[::]")).toThrow()
+    })
+
     it("should block localhost when allowLocalhost is false", () => {
       const schema = url(true, { allowLocalhost: false })
       expect(() => schema.parse("http://localhost:3000")).toThrow()
@@ -456,7 +465,16 @@ describe("url", () => {
       expect(() => schema.parse("http://10.0.0.1")).toThrow()
       expect(() => schema.parse("http://172.16.0.1")).toThrow()
       expect(() => schema.parse("http://192.168.0.1")).toThrow()
+      expect(() => schema.parse("http://169.254.0.1")).toThrow()
+      expect(() => schema.parse("http://[fc00::1]")).toThrow()
+      expect(() => schema.parse("http://[fe80::1]")).toThrow()
+      expect(() => schema.parse("http://[fe81::1]")).toThrow()
+      expect(() => schema.parse("http://[febf::1]")).toThrow()
+      expect(() => schema.parse("http://[::ffff:127.0.0.1]")).toThrow()
+      expect(() => schema.parse("http://[::ffff:10.0.0.1]")).toThrow()
       expect(schema.parse("https://8.8.8.8")).toBe("https://8.8.8.8") // Public IP
+      expect(schema.parse("http://[::ffff:8.8.8.8]")).toBe("http://[::ffff:8.8.8.8]") // IPv4-mapped public IP
+      expect(schema.parse("https://fc.example.com")).toBe("https://fc.example.com")
     })
 
     it("should handle edge cases with ports", () => {

package/tests/taiwan/tel.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach } from "vitest"
-import { twTel, setLocale, validateTaiwanTel } from "../../src"
+import { twTel, setLocale, validateTaiwanTel, validateTaiwanInternationalTollFree } from "../../src"
 
 describe("Taiwan twTel(true) validator", () => {
   beforeEach(() => setLocale("en-US"))
@@ -45,7 +45,7 @@ describe("Taiwan twTel(true) validator", () => {
       expect(schema.parse("07012345678")).toBe("07012345678") // 070-1234-5678 (11 digits)
       expect(schema.parse("070-1234-5678")).toBe("070-1234-5678") // with separators
 
-      // Toll-free numbers
+      // Domestic recipient-paid/toll-free numbers
       expect(schema.parse("0800123456")).toBe("0800123456") // 0800-123-456 (10 digits)
       expect(schema.parse("0809123456")).toBe("0809123456") // 0809-123-456 (10 digits)
       expect(schema.parse("0800-012-345")).toBe("0800-012-345") // with separators
@@ -70,6 +70,40 @@ describe("Taiwan twTel(true) validator", () => {
       expect(schema.parse("07 234-5678")).toBe("07 234-5678")
     })
 
+    it("should validate Taiwan international toll-free numbers when ITFS is allowed", () => {
+      const schema = twTel(true, { allowITFS: true })
+
+      expect(schema.parse("00800-2468-1668")).toBe("00800-2468-1668")
+      expect(schema.parse("00801128000")).toBe("00801128000")
+      expect(schema.parse("00801-852-747")).toBe("00801-852-747")
+      expect(schema.parse("00809 123456789012")).toBe("00809 123456789012")
+
+      expect(validateTaiwanTel("00800-2468-1668", { allowITFS: true })).toBe(true)
+      expect(validateTaiwanTel("00801-852-747", { allowITFS: true })).toBe(true)
+    })
+
+    it("should reject Taiwan international toll-free numbers unless ITFS is allowed", () => {
+      const schema = twTel(true)
+
+      expect(() => schema.parse("00800-2468-1668")).toThrow("Invalid Taiwan telephone format")
+      expect(() => schema.parse("00801-852-747")).toThrow("Invalid Taiwan telephone format")
+      expect(validateTaiwanTel("00801-852-747")).toBe(false)
+    })
+
+    it("should reject invalid Taiwan international toll-free number lengths", () => {
+      const schema = twTel(true, { allowITFS: true })
+
+      expect(() => schema.parse("00800-1234-567")).toThrow("Invalid Taiwan telephone format")
+      expect(() => schema.parse("00800-1234-56789")).toThrow("Invalid Taiwan telephone format")
+      expect(() => schema.parse("00801")).toThrow("Invalid Taiwan telephone format")
+      expect(() => schema.parse("00801-1234567890123")).toThrow("Invalid Taiwan telephone format")
+
+      expect(validateTaiwanInternationalTollFree("00800-1234-5678")).toBe(true)
+      expect(validateTaiwanInternationalTollFree("00800-1234-567")).toBe(false)
+      expect(validateTaiwanInternationalTollFree("00801-123456789012")).toBe(true)
+      expect(validateTaiwanInternationalTollFree("00801-1234567890123")).toBe(false)
+    })
+
     it("should reject invalid Taiwan telephone numbers", () => {
       const schema = twTel(true)
 
@@ -265,7 +299,7 @@ describe("Taiwan twTel(true) validator", () => {
         expect(validateTaiwanTel("070-1234-5678")).toBe(true) // 070 with separators
         expect(validateTaiwanTel("07001234567")).toBe(true) // 070 starting with 0 (valid VoIP)
 
-        // Toll-free numbers
+        // Domestic recipient-paid/toll-free numbers
         expect(validateTaiwanTel("0800123456")).toBe(true) // 0800
         expect(validateTaiwanTel("0809123456")).toBe(true) // 0809
         expect(validateTaiwanTel("0800-123-456")).toBe(true) // with separators
@@ -393,8 +427,8 @@ describe("Taiwan twTel(true) validator", () => {
         { code: "082", numbers: ["082234567"] }, // Kinmen (9 digits, first digit 2) - from utility test ✓
         { code: "089", numbers: ["089234567"] }, // Taitung (9 digits, first digit 2) - from utility test ✓
         { code: "070", numbers: ["07012345678"] }, // VoIP (11 digits)
-        { code: "0800", numbers: ["0800123456"] }, // Toll-free (10 digits)
-        { code: "0809", numbers: ["0809123456"] }, // Toll-free (10 digits)
+        { code: "0800", numbers: ["0800123456"] }, // Domestic recipient-paid/toll-free (10 digits)
+        { code: "0809", numbers: ["0809123456"] }, // Domestic recipient-paid/toll-free (10 digits)
         { code: "0826", numbers: ["082661234"] }, // Wuqiu (9 digits, first digit 6) - from utility test ✓
         { code: "0836", numbers: ["083621234"] }, // Matsu (9 digits, first digit 2) - from utility test ✓
       ]

package/tsconfig.json

@@ -2,7 +2,8 @@
   "compilerOptions": {
     "target": "ESNext",
     "module": "ESNext",
-    "moduleResolution": "Node",
+    "moduleResolution": "Bundler",
+    "ignoreDeprecations": "6.0",
     "esModuleInterop": true,
     "declaration": true,
     "outDir": "./dist",