taiwan-validator 1.0.0 → 1.2.0

package/src/validators/national-id.ts

@@ -1,45 +1,14 @@
-import type { ValidationResult, NationalIdType } from "../types";
+import type { ValidationResult, NationalIdType, NationalIdInfo } from "../types";
+import { LETTER_MAPPING, REGION_MAPPING } from "./shared";
 
 /**
- * 字母對應數字表（用於身分證字號驗證）
- */
-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個數字）
+ * 驗證台灣身分證字號格式與檢查碼（1個字母 + 9個數字）
  * 格式：A123456789
  * - 第一個字元：地區代碼（字母）
  * - 第二個字元：性別（1 = 男性，2 = 女性）
  * - 最後一個字元：檢查碼
  */
-function validateOldFormat(id: string): boolean {
+function validateFormatAndChecksum(id: string): boolean {
   const pattern = /^[A-Z][12]\d{8}$/;
   if (!pattern.test(id)) {
     return false;
@@ -50,7 +19,6 @@ function validateOldFormat(id: string): boolean {
 
   const letterValue = LETTER_MAPPING[letter] as number;
 
-  // 計算檢查碼
   const d1 = Math.floor(letterValue / 10);
   const d2 = letterValue % 10;
 
@@ -66,70 +34,19 @@ function validateOldFormat(id: string): boolean {
 }
 
 /**
- * 驗證新式身分證字號格式（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;
-}
-
-/**
- * 驗證台灣身分證字號（支援新舊格式）
+ * 驗證台灣身分證字號（身分證字號皆為「1個字母 + 9個數字」格式）
  * @param id - 要驗證的身分證字號
- * @param format - 可選：指定格式類型（'old' 或 'new'）
+ * @param format - 可選（為維持相容性保留）：指定格式類型
  * @returns 驗證結果
  *
  * @example
  * ```typescript
- * validateNationalId('A123456789'); // 舊式格式
- * validateNationalId('AA12345678'); // 新式格式
+ * validateNationalId('A123456789');
  * ```
  */
 export function validateNationalId(
   id: string,
-  format?: NationalIdType,
+  _format?: NationalIdType,
 ): ValidationResult {
   if (!id || typeof id !== "string") {
     return {
@@ -140,42 +57,52 @@ export function validateNationalId(
 
   const normalizedId = id.trim().toUpperCase();
 
-  // 如果指定了格式，只驗證該格式
-  if (format === "old") {
-    const isValid = validateOldFormat(normalizedId);
-    return {
-      isValid,
-      message: isValid ? undefined : "無效的舊式身分證字號",
-    };
-  }
+  const isValid = validateFormatAndChecksum(normalizedId);
+
+  return {
+    isValid,
+    message: isValid ? undefined : "無效的身分證字號",
+  };
+}
 
-  if (format === "new") {
-    const isValid = validateNewFormat(normalizedId);
+/**
+ * 解析台灣身分證字號資訊（性別、發證地區）
+ * @param id - 要解析的身分證字號
+ * @returns 解析結果，包含驗證狀態及相關欄位
+ *
+ * @example
+ * ```typescript
+ * parseNationalId('A123456789');
+ * // 輸出: { isValid: true, gender: 'male', region: '臺北市' }
+ * ```
+ */
+export function parseNationalId(id: string): NationalIdInfo {
+  if (!id || typeof id !== "string") {
     return {
-      isValid,
-      message: isValid ? undefined : "無效的新式身分證字號",
+      isValid: false,
+      message: "身分證字號必須為非空字串",
     };
   }
 
-  // 自動偵測格式
-  const detectedFormat = detectFormat(normalizedId);
+  const normalizedId = id.trim().toUpperCase();
 
-  if (!detectedFormat) {
+  const isValid = validateFormatAndChecksum(normalizedId);
+  if (!isValid) {
     return {
       isValid: false,
-      message: "無效的身分證字號格式",
+      message: "無效的身分證字號",
     };
   }
 
-  const isValid =
-    detectedFormat === "old"
-      ? validateOldFormat(normalizedId)
-      : validateNewFormat(normalizedId);
+  const firstLetter = normalizedId[0] as string;
+  const genderDigit = normalizedId[1] as string;
+
+  const gender = genderDigit === "1" ? "male" : "female";
+  const region = REGION_MAPPING[firstLetter] as string;
 
   return {
-    isValid,
-    message: isValid
-      ? undefined
-      : `無效的${detectedFormat === "old" ? "舊式" : "新式"}身分證字號`,
+    isValid: true,
+    gender,
+    region,
   };
 }

package/src/validators/nhi-card.test.ts

@@ -0,0 +1,21 @@
+import { validateNHICard } from "./nhi-card";
+
+describe("validateNHICard", () => {
+  test("should validate correct NHI card numbers", () => {
+    expect(validateNHICard("0000 1234 5678").isValid).toBe(true);
+    expect(validateNHICard("000012345678").isValid).toBe(true);
+    expect(validateNHICard("0000-1234-5678").isValid).toBe(true);
+  });
+
+  test("should reject invalid NHI card numbers", () => {
+    expect(validateNHICard("00001234567").isValid).toBe(false); // Too short (11 digits)
+    expect(validateNHICard("0000123456789").isValid).toBe(false); // Too long (13 digits)
+    expect(validateNHICard("00001234567a").isValid).toBe(false); // Non-numeric
+  });
+
+  test("should reject empty or non-string inputs", () => {
+    expect(validateNHICard("").isValid).toBe(false);
+    // @ts-expect-error Testing invalid input type
+    expect(validateNHICard(null).isValid).toBe(false);
+  });
+});

package/src/validators/nhi-card.ts

@@ -0,0 +1,39 @@
+import type { ValidationResult } from "../types";
+
+/**
+ * 驗證台灣國民健康保險卡（健保卡）卡號格式
+ * 格式為 12 碼數字（可包含減號或空格，如 0000 1234 5678）
+ *
+ * @param cardNumber - 要驗證的健保卡卡號
+ * @returns 驗證結果
+ *
+ * @example
+ * ```typescript
+ * validateNHICard('0000 1234 5678'); // { isValid: true }
+ * validateNHICard('000012345678');   // { isValid: true }
+ * ```
+ */
+export function validateNHICard(cardNumber: string): ValidationResult {
+  if (!cardNumber || typeof cardNumber !== "string") {
+    return {
+      isValid: false,
+      message: "健保卡號必須為非空字串",
+    };
+  }
+
+  // 去除空格與減號
+  const normalized = cardNumber.replace(/[-\s]/g, "");
+
+  const pattern = /^\d{12}$/;
+
+  if (!pattern.test(normalized)) {
+    return {
+      isValid: false,
+      message: "健保卡號格式必須為12碼數字",
+    };
+  }
+
+  return {
+    isValid: true,
+  };
+}

package/src/validators/passport.test.ts

@@ -0,0 +1,20 @@
+import { validatePassport } from "./passport";
+
+describe("validatePassport", () => {
+  test("should validate correct passport numbers", () => {
+    expect(validatePassport("312345678").isValid).toBe(true);
+    expect(validatePassport("123456789").isValid).toBe(true);
+  });
+
+  test("should reject invalid passport numbers", () => {
+    expect(validatePassport("12345678").isValid).toBe(false); // Too short (8 digits)
+    expect(validatePassport("1234567890").isValid).toBe(false); // Too long (10 digits)
+    expect(validatePassport("12345678a").isValid).toBe(false); // Non-numeric
+  });
+
+  test("should reject empty or non-string inputs", () => {
+    expect(validatePassport("").isValid).toBe(false);
+    // @ts-expect-error Testing invalid input type
+    expect(validatePassport(null).isValid).toBe(false);
+  });
+});

package/src/validators/passport.ts

@@ -0,0 +1,38 @@
+import type { ValidationResult } from "../types";
+
+/**
+ * 驗證中華民國（台灣）護照號碼格式
+ * 晶片護照與一般護照為 9 碼數字格式（晶片護照通常以 3 開頭）
+ *
+ * @param passport - 要驗證的護照號碼
+ * @returns 驗證結果
+ *
+ * @example
+ * ```typescript
+ * validatePassport('312345678'); // { isValid: true }
+ * ```
+ */
+export function validatePassport(passport: string): ValidationResult {
+  if (!passport || typeof passport !== "string") {
+    return {
+      isValid: false,
+      message: "護照號碼必須為非空字串",
+    };
+  }
+
+  const normalized = passport.trim();
+
+  // 驗證 9 碼數字
+  const pattern = /^\d{9}$/;
+
+  if (!pattern.test(normalized)) {
+    return {
+      isValid: false,
+      message: "護照號碼格式必須為9位數字",
+    };
+  }
+
+  return {
+    isValid: true,
+  };
+}

package/src/validators/postal-code.test.ts

@@ -0,0 +1,31 @@
+import { validatePostalCode } from "./postal-code";
+
+describe("validatePostalCode", () => {
+  test("should validate correct postal codes", () => {
+    // 3 digits
+    expect(validatePostalCode("100").isValid).toBe(true);
+    expect(validatePostalCode(100).isValid).toBe(true);
+    
+    // 5 digits
+    expect(validatePostalCode("100-01").isValid).toBe(true);
+    expect(validatePostalCode("10001").isValid).toBe(true);
+    
+    // 6 digits
+    expect(validatePostalCode("100001").isValid).toBe(true);
+    expect(validatePostalCode("100-001").isValid).toBe(true);
+  });
+
+  test("should reject invalid postal codes", () => {
+    expect(validatePostalCode("001").isValid).toBe(false); // First digit cannot be 0
+    expect(validatePostalCode("10").isValid).toBe(false); // Too short
+    expect(validatePostalCode("1000").isValid).toBe(false); // 4 digits is not valid
+    expect(validatePostalCode("1000001").isValid).toBe(false); // Too long (7 digits)
+  });
+
+  test("should reject empty or null inputs", () => {
+    // @ts-expect-error Testing invalid input type
+    expect(validatePostalCode(null).isValid).toBe(false);
+    // @ts-expect-error Testing invalid input type
+    expect(validatePostalCode(undefined).isValid).toBe(false);
+  });
+});

package/src/validators/postal-code.ts

@@ -0,0 +1,41 @@
+import type { ValidationResult } from "../types";
+
+/**
+ * 驗證台灣郵遞區號格式
+ * 支援 3 碼、5 碼 (3+2) 及新式 6 碼 (3+3) 格式（可包含減號，如 100-001 或 100001）
+ * 第一碼必須為 1-9
+ *
+ * @param code - 要驗證的郵遞區號
+ * @returns 驗證結果
+ *
+ * @example
+ * ```typescript
+ * validatePostalCode('100');     // { isValid: true }
+ * validatePostalCode('100-01');  // { isValid: true }
+ * validatePostalCode('100001');  // { isValid: true }
+ * ```
+ */
+export function validatePostalCode(code: string | number): ValidationResult {
+  if (code === null || code === undefined) {
+    return {
+      isValid: false,
+      message: "郵遞區號必須為非空字串或數字",
+    };
+  }
+
+  const strCode = String(code).trim().replace(/[-\s]/g, "");
+
+  // 驗證格式：3 碼、5 碼或 6 碼，且首碼為 1-9
+  const pattern = /^[1-9]\d{2}$|^[1-9]\d{4}$|^[1-9]\d{5}$/;
+
+  if (!pattern.test(strCode)) {
+    return {
+      isValid: false,
+      message: "郵遞區號格式必須為首碼非0的3碼、5碼或6碼數字",
+    };
+  }
+
+  return {
+    isValid: true,
+  };
+}

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

@@ -1,101 +1,62 @@
-import { validateResidentCertificate } from "./resident-certificate";
+import { validateResidentCertificate, parseResidentCertificate } 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,
-      );
+  describe("New Format (1 letter + 9 digits, e.g. A823456783)", () => {
+    test("should validate correct new format Resident Certificates", () => {
+      expect(validateResidentCertificate("A823456783", "new").isValid).toBe(true);
+      expect(validateResidentCertificate("B923456786", "new").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 reject invalid new format Resident Certificates", () => {
+      expect(validateResidentCertificate("A823456780", "new").isValid).toBe(false); // Wrong checksum
+      expect(validateResidentCertificate("E723456783", "new").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,
-      );
+      expect(validateResidentCertificate("a823456783", "new").isValid).toBe(true);
+      expect(validateResidentCertificate("b923456786", "new").isValid).toBe(true);
     });
 
     test("should handle whitespace", () => {
-      expect(validateResidentCertificate(" A823456783 ", "old").isValid).toBe(
-        true,
-      );
+      expect(validateResidentCertificate(" A823456783 ", "new").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,
-      );
+  describe("Old Format (2 letters + 8 digits, e.g. AB12345677)", () => {
+    test("should validate correct old format Resident Certificates", () => {
+      expect(validateResidentCertificate("AB12345677", "old").isValid).toBe(true); // Female non-citizen
+      expect(validateResidentCertificate("AC12345679", "old").isValid).toBe(true); // Male foreigner
+      expect(validateResidentCertificate("AD12345671", "old").isValid).toBe(true); // Female foreigner
+      expect(validateResidentCertificate("AA12345675", "old").isValid).toBe(true); // Male non-citizen
     });
 
-    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 reject invalid old format Resident Certificates", () => {
+      expect(validateResidentCertificate("AB12345678", "old").isValid).toBe(false); // Wrong checksum
+      expect(validateResidentCertificate("AE12345678", "old").isValid).toBe(false); // Invalid second letter (must be A-D)
     });
 
     test("should handle case insensitive input", () => {
-      expect(validateResidentCertificate("aa23456786", "new").isValid).toBe(
-        true,
-      );
-    });
-
-    test("should handle whitespace", () => {
-      expect(validateResidentCertificate(" AB23456789 ", "new").isValid).toBe(
-        true,
-      );
+      expect(validateResidentCertificate("ab12345677", "old").isValid).toBe(true);
     });
   });
 
   describe("Auto-detect Format", () => {
     test("should auto-detect and validate old format", () => {
-      expect(validateResidentCertificate("A823456783").isValid).toBe(true);
+      expect(validateResidentCertificate("AB12345677").isValid).toBe(true);
     });
 
     test("should auto-detect and reject invalid old format", () => {
-      const result = validateResidentCertificate("A823456780");
+      const result = validateResidentCertificate("AB12345678");
       expect(result.isValid).toBe(false);
       expect(result.message).toBe("無效的舊式居留證號");
     });
 
     test("should auto-detect and validate new format", () => {
-      expect(validateResidentCertificate("AA23456786").isValid).toBe(true);
+      expect(validateResidentCertificate("A823456783").isValid).toBe(true);
     });
 
     test("should auto-detect and reject invalid new format", () => {
-      const result = validateResidentCertificate("AA23456780");
+      const result = validateResidentCertificate("A823456780");
       expect(result.isValid).toBe(false);
       expect(result.message).toBe("無效的新式居留證號");
     });
@@ -106,6 +67,40 @@ describe("validateResidentCertificate", () => {
     });
   });
 
+  describe("Parser (parseResidentCertificate)", () => {
+    test("should parse new format Resident Certificates", () => {
+      const parsed = parseResidentCertificate("A823456783");
+      expect(parsed.isValid).toBe(true);
+      expect(parsed.format).toBe("new");
+      expect(parsed.gender).toBe("male");
+      expect(parsed.region).toBe("臺北市");
+      expect(parsed.identityType).toBe("foreigner");
+    });
+
+    test("should parse old format Resident Certificates", () => {
+      const parsed1 = parseResidentCertificate("AB12345677");
+      expect(parsed1.isValid).toBe(true);
+      expect(parsed1.format).toBe("old");
+      expect(parsed1.gender).toBe("female");
+      expect(parsed1.region).toBe("臺北市");
+      expect(parsed1.identityType).toBe("non-citizen");
+
+      const parsed2 = parseResidentCertificate("AC12345679");
+      expect(parsed2.isValid).toBe(true);
+      expect(parsed2.format).toBe("old");
+      expect(parsed2.gender).toBe("male");
+      expect(parsed2.region).toBe("臺北市");
+      expect(parsed2.identityType).toBe("foreigner");
+    });
+
+    test("should return isValid: false for invalid resident certificates", () => {
+      const parsed = parseResidentCertificate("A823456780");
+      expect(parsed.isValid).toBe(false);
+      expect(parsed.format).toBeUndefined();
+      expect(parsed.message).toBe("無效的新式居留證號");
+    });
+  });
+
   describe("Edge Cases", () => {
     test("should reject empty or invalid input", () => {
       expect(validateResidentCertificate("").isValid).toBe(false);
@@ -117,7 +112,7 @@ describe("validateResidentCertificate", () => {
     });
 
     test("should provide meaningful error messages", () => {
-      const result1 = validateResidentCertificate("A823456780", "old");
+      const result1 = validateResidentCertificate("A823456780", "new");
       expect(result1.isValid).toBe(false);
       expect(result1.message).toBeDefined();