taiwan-validator 1.0.0

package/src/validators/mobile-phone.test.ts

@@ -0,0 +1,67 @@
+import { validateMobilePhone } from "./mobile-phone";
+
+describe("validateMobilePhone", () => {
+  describe("Valid Mobile Phone Numbers", () => {
+    test("should validate correct mobile phone numbers", () => {
+      expect(validateMobilePhone("0912345678").isValid).toBe(true);
+      expect(validateMobilePhone("0923456789").isValid).toBe(true);
+      expect(validateMobilePhone("0934567890").isValid).toBe(true);
+      expect(validateMobilePhone("0945678901").isValid).toBe(true);
+      expect(validateMobilePhone("0956789012").isValid).toBe(true);
+      expect(validateMobilePhone("0967890123").isValid).toBe(true);
+      expect(validateMobilePhone("0978901234").isValid).toBe(true);
+      expect(validateMobilePhone("0989012345").isValid).toBe(true);
+    });
+
+    test("should validate phone numbers with separators", () => {
+      expect(validateMobilePhone("0912-345-678").isValid).toBe(true);
+      expect(validateMobilePhone("0912 345 678").isValid).toBe(true);
+      expect(validateMobilePhone("(0912) 345-678").isValid).toBe(true);
+      expect(validateMobilePhone("0912-345678").isValid).toBe(true);
+    });
+  });
+
+  describe("Invalid Mobile Phone Numbers", () => {
+    test("should reject numbers not starting with 09", () => {
+      expect(validateMobilePhone("0812345678").isValid).toBe(false);
+      expect(validateMobilePhone("0712345678").isValid).toBe(false);
+      expect(validateMobilePhone("1912345678").isValid).toBe(false);
+    });
+
+    test("should reject incorrect length", () => {
+      expect(validateMobilePhone("091234567").isValid).toBe(false); // Too short
+      expect(validateMobilePhone("09123456789").isValid).toBe(false); // Too long
+    });
+
+    test("should reject non-numeric input (excluding valid separators)", () => {
+      expect(validateMobilePhone("091234567A").isValid).toBe(false);
+      expect(validateMobilePhone("ABCDEFGHIJ").isValid).toBe(false);
+    });
+  });
+
+  describe("Edge Cases", () => {
+    test("should handle whitespace", () => {
+      expect(validateMobilePhone(" 0912345678 ").isValid).toBe(true);
+      expect(validateMobilePhone("0912 345 678").isValid).toBe(true);
+    });
+
+    test("should reject empty or invalid input", () => {
+      expect(validateMobilePhone("").isValid).toBe(false);
+      expect(validateMobilePhone("   ").isValid).toBe(false);
+      // @ts-expect-error Testing invalid input type
+      expect(validateMobilePhone(null).isValid).toBe(false);
+      // @ts-expect-error Testing invalid input type
+      expect(validateMobilePhone(undefined).isValid).toBe(false);
+    });
+
+    test("should provide meaningful error messages", () => {
+      const result1 = validateMobilePhone("091234567");
+      expect(result1.isValid).toBe(false);
+      expect(result1.message).toBe("手機號碼必須以09開頭且為10位數字");
+
+      const result2 = validateMobilePhone("");
+      expect(result2.isValid).toBe(false);
+      expect(result2.message).toBe("手機號碼必須為非空字串");
+    });
+  });
+});

package/src/validators/mobile-phone.ts

@@ -0,0 +1,41 @@
+import type { ValidationResult } from "../types";
+
+/**
+ * 驗證台灣手機號碼
+ * 格式：09XXXXXXXX（10位數字，以09開頭）
+ *
+ * @param phone - 要驗證的手機號碼
+ * @returns 驗證結果
+ *
+ * @example
+ * ```typescript
+ * validateMobilePhone('0912345678');
+ * validateMobilePhone('0912-345-678'); // 含分隔符號
+ * ```
+ */
+export function validateMobilePhone(phone: string): ValidationResult {
+  if (!phone || typeof phone !== "string") {
+    return {
+      isValid: false,
+      message: "手機號碼必須為非空字串",
+    };
+  }
+
+  // 移除常見的分隔符號（空格、破折號、括號）
+  const normalized = phone.trim().replace(/[\s\-()]/g, "");
+
+  // 檢查是否符合台灣手機號碼格式
+  // 以09開頭且總共10位數字
+  const pattern = /^09\d{8}$/;
+
+  if (!pattern.test(normalized)) {
+    return {
+      isValid: false,
+      message: "手機號碼必須以09開頭且為10位數字",
+    };
+  }
+
+  return {
+    isValid: true,
+  };
+}

package/src/validators/national-id.test.ts

@@ -0,0 +1,99 @@
+import { validateNationalId } from "./national-id";
+
+describe("validateNationalId", () => {
+  describe("Old Format", () => {
+    test("should validate correct old format National IDs", () => {
+      // These are example format IDs (not real person IDs)
+      expect(validateNationalId("A123456789", "old").isValid).toBe(true);
+      expect(validateNationalId("F223456786", "old").isValid).toBe(true);
+      expect(validateNationalId("O123456782", "old").isValid).toBe(true);
+    });
+
+    test("should reject invalid old format National IDs", () => {
+      expect(validateNationalId("A123456788", "old").isValid).toBe(false); // Wrong checksum
+      expect(validateNationalId("A323456789", "old").isValid).toBe(false); // Invalid gender code
+      expect(validateNationalId("A12345678", "old").isValid).toBe(false); // Too short
+      expect(validateNationalId("A1234567890", "old").isValid).toBe(false); // Too long
+    });
+
+    test("should handle case insensitive input", () => {
+      expect(validateNationalId("a123456789", "old").isValid).toBe(true);
+      expect(validateNationalId("f223456786", "old").isValid).toBe(true);
+    });
+
+    test("should handle whitespace", () => {
+      expect(validateNationalId(" A123456789 ", "old").isValid).toBe(true);
+    });
+  });
+
+  describe("New Format", () => {
+    test("should validate correct new format National IDs", () => {
+      // These are example format IDs (not real person IDs)
+      expect(validateNationalId("AA23456786", "new").isValid).toBe(true);
+      expect(validateNationalId("AB23456789", "new").isValid).toBe(true);
+    });
+
+    test("should reject invalid new format National IDs", () => {
+      expect(validateNationalId("AA12345677", "new").isValid).toBe(false); // Wrong checksum
+      expect(validateNationalId("AA1234567", "new").isValid).toBe(false); // Too short
+      expect(validateNationalId("AA123456789", "new").isValid).toBe(false); // Too long
+    });
+
+    test("should handle case insensitive input", () => {
+      expect(validateNationalId("aa23456786", "new").isValid).toBe(true);
+    });
+
+    test("should handle whitespace", () => {
+      expect(validateNationalId(" AB23456789 ", "new").isValid).toBe(true);
+    });
+  });
+
+  describe("Auto-detect Format", () => {
+    test("should auto-detect and validate old format", () => {
+      expect(validateNationalId("A123456789").isValid).toBe(true);
+      expect(validateNationalId("F223456786").isValid).toBe(true);
+    });
+
+    test("should auto-detect and reject invalid old format", () => {
+      const result = validateNationalId("A123456780");
+      expect(result.isValid).toBe(false);
+      expect(result.message).toBe("無效的舊式身分證字號");
+    });
+
+    test("should auto-detect and validate new format", () => {
+      expect(validateNationalId("AA23456786").isValid).toBe(true);
+    });
+
+    test("should auto-detect and reject invalid new format", () => {
+      const result = validateNationalId("AA23456780");
+      expect(result.isValid).toBe(false);
+      expect(result.message).toBe("無效的新式身分證字號");
+    });
+
+    test("should reject completely invalid formats", () => {
+      expect(validateNationalId("12345678").isValid).toBe(false);
+      expect(validateNationalId("ABCDEFGH").isValid).toBe(false);
+    });
+  });
+
+  describe("Edge Cases", () => {
+    test("should reject empty or invalid input", () => {
+      expect(validateNationalId("").isValid).toBe(false);
+      expect(validateNationalId("   ").isValid).toBe(false);
+      // @ts-expect-error Testing invalid input type
+      expect(validateNationalId(null).isValid).toBe(false);
+      // @ts-expect-error Testing invalid input type
+      expect(validateNationalId(undefined).isValid).toBe(false);
+    });
+
+    test("should provide meaningful error messages", () => {
+      const result1 = validateNationalId("A123456788", "old");
+      expect(result1.isValid).toBe(false);
+      expect(result1.message).toBeDefined();
+
+      const result2 = validateNationalId("");
+      expect(result2.isValid).toBe(false);
+      expect(result2.message).toBe("身分證字號必須為非空字串");
+    });
+  });
+});

package/src/validators/national-id.ts

@@ -0,0 +1,181 @@
+import type { ValidationResult, NationalIdType } from "../types";
+
+/**
+ * 字母對應數字表（用於身分證字號驗證）
+ */
+const LETTER_MAPPING: Record<string, number> = {
+  A: 10,
+  B: 11,
+  C: 12,
+  D: 13,
+  E: 14,
+  F: 15,
+  G: 16,
+  H: 17,
+  I: 34,
+  J: 18,
+  K: 19,
+  L: 20,
+  M: 21,
+  N: 22,
+  O: 35,
+  P: 23,
+  Q: 24,
+  R: 25,
+  S: 26,
+  T: 27,
+  U: 28,
+  V: 29,
+  W: 32,
+  X: 30,
+  Y: 31,
+  Z: 33,
+};
+
+/**
+ * 驗證舊式身分證字號格式（1個字母 + 9個數字）
+ * 格式：A123456789
+ * - 第一個字元：地區代碼（字母）
+ * - 第二個字元：性別（1 = 男性，2 = 女性）
+ * - 最後一個字元：檢查碼
+ */
+function validateOldFormat(id: string): boolean {
+  const pattern = /^[A-Z][12]\d{8}$/;
+  if (!pattern.test(id)) {
+    return false;
+  }
+
+  const letter = id[0] as string;
+  const numbers = id.slice(1);
+
+  const letterValue = LETTER_MAPPING[letter] as number;
+
+  // 計算檢查碼
+  const d1 = Math.floor(letterValue / 10);
+  const d2 = letterValue % 10;
+
+  const weights = [1, 9, 8, 7, 6, 5, 4, 3, 2, 1, 1];
+  const digits = [d1, d2, ...numbers.split("").map(Number)];
+
+  const sum = digits.reduce(
+    (acc, digit, index) => acc + digit * weights[index]!,
+    0,
+  );
+
+  return sum % 10 === 0;
+}
+
+/**
+ * 驗證新式身分證字號格式（2個字母 + 8個數字）
+ * 格式：AA12345678
+ * - 第一個字元：地區代碼（字母）
+ * - 第二個字元：性別（8 = 男性，9 = 女性）以字母表示
+ * - 最後一個字元：檢查碼
+ */
+function validateNewFormat(id: string): boolean {
+  const pattern = /^[A-Z]{2}\d{8}$/;
+  if (!pattern.test(id)) {
+    return false;
+  }
+
+  const firstLetter = id[0] as string;
+  const secondLetter = id[1] as string;
+  const numbers = id.slice(2);
+
+  const firstLetterValue = LETTER_MAPPING[firstLetter] as number;
+  const secondLetterValue = LETTER_MAPPING[secondLetter] as number;
+
+  // 計算新式格式的檢查碼
+  const d1 = Math.floor(firstLetterValue / 10);
+  const d2 = firstLetterValue % 10;
+  const d3 = Math.floor(secondLetterValue / 10);
+  const d4 = secondLetterValue % 10;
+
+  const weights = [1, 9, 8, 7, 6, 5, 4, 3, 2, 1, 1, 1];
+  const digits = [d1, d2, d3, d4, ...numbers.split("").map(Number)];
+
+  const sum = digits.reduce(
+    (acc, digit, index) => acc + digit * weights[index]!,
+    0,
+  );
+
+  return sum % 10 === 0;
+}
+
+/**
+ * 偵測身分證字號格式類型
+ */
+function detectFormat(id: string): NationalIdType | null {
+  if (/^[A-Z][12]\d{8}$/.test(id)) {
+    return "old";
+  }
+  if (/^[A-Z]{2}\d{8}$/.test(id)) {
+    return "new";
+  }
+  return null;
+}
+
+/**
+ * 驗證台灣身分證字號（支援新舊格式）
+ * @param id - 要驗證的身分證字號
+ * @param format - 可選：指定格式類型（'old' 或 'new'）
+ * @returns 驗證結果
+ *
+ * @example
+ * ```typescript
+ * validateNationalId('A123456789'); // 舊式格式
+ * validateNationalId('AA12345678'); // 新式格式
+ * ```
+ */
+export function validateNationalId(
+  id: string,
+  format?: NationalIdType,
+): ValidationResult {
+  if (!id || typeof id !== "string") {
+    return {
+      isValid: false,
+      message: "身分證字號必須為非空字串",
+    };
+  }
+
+  const normalizedId = id.trim().toUpperCase();
+
+  // 如果指定了格式，只驗證該格式
+  if (format === "old") {
+    const isValid = validateOldFormat(normalizedId);
+    return {
+      isValid,
+      message: isValid ? undefined : "無效的舊式身分證字號",
+    };
+  }
+
+  if (format === "new") {
+    const isValid = validateNewFormat(normalizedId);
+    return {
+      isValid,
+      message: isValid ? undefined : "無效的新式身分證字號",
+    };
+  }
+
+  // 自動偵測格式
+  const detectedFormat = detectFormat(normalizedId);
+
+  if (!detectedFormat) {
+    return {
+      isValid: false,
+      message: "無效的身分證字號格式",
+    };
+  }
+
+  const isValid =
+    detectedFormat === "old"
+      ? validateOldFormat(normalizedId)
+      : validateNewFormat(normalizedId);
+
+  return {
+    isValid,
+    message: isValid
+      ? undefined
+      : `無效的${detectedFormat === "old" ? "舊式" : "新式"}身分證字號`,
+  };
+}

package/src/validators/resident-certificate.test.ts

@@ -0,0 +1,129 @@
+import { validateResidentCertificate } from "./resident-certificate";
+
+describe("validateResidentCertificate", () => {
+  describe("Old Format", () => {
+    test("should validate correct old format Resident Certificates", () => {
+      // These are example format IDs (not real person IDs)
+      expect(validateResidentCertificate("A823456783", "old").isValid).toBe(
+        true,
+      );
+      expect(validateResidentCertificate("B923456786", "old").isValid).toBe(
+        true,
+      );
+      expect(validateResidentCertificate("C823456785", "old").isValid).toBe(
+        true,
+      );
+      expect(validateResidentCertificate("D923456788", "old").isValid).toBe(
+        true,
+      );
+    });
+
+    test("should reject invalid old format Resident Certificates", () => {
+      expect(validateResidentCertificate("A823456780", "old").isValid).toBe(
+        false,
+      ); // Wrong checksum
+      expect(validateResidentCertificate("E823456783", "old").isValid).toBe(
+        false,
+      ); // Invalid first letter
+      expect(validateResidentCertificate("A723456783", "old").isValid).toBe(
+        false,
+      ); // Invalid second digit (must be 8 or 9)
+    });
+
+    test("should handle case insensitive input", () => {
+      expect(validateResidentCertificate("a823456783", "old").isValid).toBe(
+        true,
+      );
+      expect(validateResidentCertificate("b923456786", "old").isValid).toBe(
+        true,
+      );
+    });
+
+    test("should handle whitespace", () => {
+      expect(validateResidentCertificate(" A823456783 ", "old").isValid).toBe(
+        true,
+      );
+    });
+  });
+
+  describe("New Format", () => {
+    test("should validate correct new format Resident Certificates", () => {
+      // These are example format IDs (not real person IDs)
+      expect(validateResidentCertificate("AA23456786", "new").isValid).toBe(
+        true,
+      );
+      expect(validateResidentCertificate("AB23456789", "new").isValid).toBe(
+        true,
+      );
+    });
+
+    test("should reject invalid new format Resident Certificates", () => {
+      expect(validateResidentCertificate("AA23456780", "new").isValid).toBe(
+        false,
+      ); // Wrong checksum
+      expect(validateResidentCertificate("AA2345678", "new").isValid).toBe(
+        false,
+      ); // Too short
+    });
+
+    test("should handle case insensitive input", () => {
+      expect(validateResidentCertificate("aa23456786", "new").isValid).toBe(
+        true,
+      );
+    });
+
+    test("should handle whitespace", () => {
+      expect(validateResidentCertificate(" AB23456789 ", "new").isValid).toBe(
+        true,
+      );
+    });
+  });
+
+  describe("Auto-detect Format", () => {
+    test("should auto-detect and validate old format", () => {
+      expect(validateResidentCertificate("A823456783").isValid).toBe(true);
+    });
+
+    test("should auto-detect and reject invalid old format", () => {
+      const result = validateResidentCertificate("A823456780");
+      expect(result.isValid).toBe(false);
+      expect(result.message).toBe("無效的舊式居留證號");
+    });
+
+    test("should auto-detect and validate new format", () => {
+      expect(validateResidentCertificate("AA23456786").isValid).toBe(true);
+    });
+
+    test("should auto-detect and reject invalid new format", () => {
+      const result = validateResidentCertificate("AA23456780");
+      expect(result.isValid).toBe(false);
+      expect(result.message).toBe("無效的新式居留證號");
+    });
+
+    test("should reject completely invalid formats", () => {
+      expect(validateResidentCertificate("12345678").isValid).toBe(false);
+      expect(validateResidentCertificate("ABCDEFGH").isValid).toBe(false);
+    });
+  });
+
+  describe("Edge Cases", () => {
+    test("should reject empty or invalid input", () => {
+      expect(validateResidentCertificate("").isValid).toBe(false);
+      expect(validateResidentCertificate("   ").isValid).toBe(false);
+      // @ts-expect-error Testing invalid input type
+      expect(validateResidentCertificate(null).isValid).toBe(false);
+      // @ts-expect-error Testing invalid input type
+      expect(validateResidentCertificate(undefined).isValid).toBe(false);
+    });
+
+    test("should provide meaningful error messages", () => {
+      const result1 = validateResidentCertificate("A823456780", "old");
+      expect(result1.isValid).toBe(false);
+      expect(result1.message).toBeDefined();
+
+      const result2 = validateResidentCertificate("");
+      expect(result2.isValid).toBe(false);
+      expect(result2.message).toBe("居留證號必須為非空字串");
+    });
+  });
+});

package/src/validators/resident-certificate.ts

@@ -0,0 +1,181 @@
+import type { ValidationResult, ResidentCertificateType } from "../types";
+
+/**
+ * 字母對應數字表（用於居留證號驗證）
+ */
+const LETTER_MAPPING: Record<string, number> = {
+  A: 10,
+  B: 11,
+  C: 12,
+  D: 13,
+  E: 14,
+  F: 15,
+  G: 16,
+  H: 17,
+  I: 34,
+  J: 18,
+  K: 19,
+  L: 20,
+  M: 21,
+  N: 22,
+  O: 35,
+  P: 23,
+  Q: 24,
+  R: 25,
+  S: 26,
+  T: 27,
+  U: 28,
+  V: 29,
+  W: 32,
+  X: 30,
+  Y: 31,
+  Z: 33,
+};
+
+/**
+ * 驗證舊式居留證號格式（1個字母 + 9個數字）
+ * 格式：A800000000
+ * - 第一個字元：地區代碼（A、B、C 或 D 表示外國人士）
+ * - 第二個字元：性別/類型（8 = 男性，9 = 女性）
+ * - 最後一個字元：檢查碼
+ */
+function validateOldFormat(id: string): boolean {
+  const pattern = /^[A-D][89]\d{8}$/;
+  if (!pattern.test(id)) {
+    return false;
+  }
+
+  const letter = id[0] as string;
+  const numbers = id.slice(1);
+
+  const letterValue = LETTER_MAPPING[letter] as number;
+
+  // 計算檢查碼（與身分證字號相同的演算法）
+  const d1 = Math.floor(letterValue / 10);
+  const d2 = letterValue % 10;
+
+  const weights = [1, 9, 8, 7, 6, 5, 4, 3, 2, 1, 1];
+  const digits = [d1, d2, ...numbers.split("").map(Number)];
+
+  const sum = digits.reduce(
+    (acc, digit, index) => acc + digit * weights[index]!,
+    0,
+  );
+
+  return sum % 10 === 0;
+}
+
+/**
+ * 驗證新式居留證號格式（2個字母 + 8個數字）
+ * 格式：AA12345678
+ * - 第一個字元：地區代碼（字母）
+ * - 第二個字元：性別（8 = 男性，9 = 女性）以字母表示
+ * - 最後一個字元：檢查碼
+ */
+function validateNewFormat(id: string): boolean {
+  const pattern = /^[A-Z]{2}\d{8}$/;
+  if (!pattern.test(id)) {
+    return false;
+  }
+
+  const firstLetter = id[0] as string;
+  const secondLetter = id[1] as string;
+  const numbers = id.slice(2);
+
+  const firstLetterValue = LETTER_MAPPING[firstLetter] as number;
+  const secondLetterValue = LETTER_MAPPING[secondLetter] as number;
+
+  // 計算新式格式的檢查碼
+  const d1 = Math.floor(firstLetterValue / 10);
+  const d2 = firstLetterValue % 10;
+  const d3 = Math.floor(secondLetterValue / 10);
+  const d4 = secondLetterValue % 10;
+
+  const weights = [1, 9, 8, 7, 6, 5, 4, 3, 2, 1, 1, 1];
+  const digits = [d1, d2, d3, d4, ...numbers.split("").map(Number)];
+
+  const sum = digits.reduce(
+    (acc, digit, index) => acc + digit * weights[index]!,
+    0,
+  );
+
+  return sum % 10 === 0;
+}
+
+/**
+ * 偵測居留證號格式類型
+ */
+function detectFormat(id: string): ResidentCertificateType | null {
+  if (/^[A-D][89]\d{8}$/.test(id)) {
+    return "old";
+  }
+  if (/^[A-Z]{2}\d{8}$/.test(id)) {
+    return "new";
+  }
+  return null;
+}
+
+/**
+ * 驗證台灣居留證號（支援新舊格式）
+ * @param id - 要驗證的居留證號
+ * @param format - 可選：指定格式類型（'old' 或 'new'）
+ * @returns 驗證結果
+ *
+ * @example
+ * ```typescript
+ * validateResidentCertificate('A800000000'); // 舊式格式
+ * validateResidentCertificate('AA12345678'); // 新式格式
+ * ```
+ */
+export function validateResidentCertificate(
+  id: string,
+  format?: ResidentCertificateType,
+): ValidationResult {
+  if (!id || typeof id !== "string") {
+    return {
+      isValid: false,
+      message: "居留證號必須為非空字串",
+    };
+  }
+
+  const normalizedId = id.trim().toUpperCase();
+
+  // 如果指定了格式，只驗證該格式
+  if (format === "old") {
+    const isValid = validateOldFormat(normalizedId);
+    return {
+      isValid,
+      message: isValid ? undefined : "無效的舊式居留證號",
+    };
+  }
+
+  if (format === "new") {
+    const isValid = validateNewFormat(normalizedId);
+    return {
+      isValid,
+      message: isValid ? undefined : "無效的新式居留證號",
+    };
+  }
+
+  // 自動偵測格式
+  const detectedFormat = detectFormat(normalizedId);
+
+  if (!detectedFormat) {
+    return {
+      isValid: false,
+      message: "無效的居留證號格式",
+    };
+  }
+
+  const isValid =
+    detectedFormat === "old"
+      ? validateOldFormat(normalizedId)
+      : validateNewFormat(normalizedId);
+
+  return {
+    isValid,
+    message: isValid
+      ? undefined
+      : `無效的${detectedFormat === "old" ? "舊式" : "新式"}居留證號`,
+  };
+}