taiwan-validator 1.1.0 → 1.2.0

package/src/validators/resident-certificate.ts

@@ -1,61 +1,32 @@
-import type { ValidationResult, ResidentCertificateType } from "../types";
+import type { ValidationResult, ResidentCertificateType, ResidentCertificateInfo } 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個數字）
- * 格式：A800000000
- * - 第一個字元：地區代碼（A、B、C 或 D 表示外國人士）
- * - 第二個字元：性別/類型（8 = 男性，9 = 女性）
+ * 驗證舊式居留證號格式與檢查碼（2個字母 + 8個數字）
+ * 格式：AA12345678
+ * - 第一個字元：地區代碼（字母）
+ * - 第二個字元：身分與性別碼（A = 男性無戶籍國民/港澳陸居民，B = 女性無戶籍國民/港澳陸居民，C = 男性外國人，D = 女性外國人）
  * - 最後一個字元：檢查碼
  */
 function validateOldFormat(id: string): boolean {
-  const pattern = /^[A-D][89]\d{8}$/;
+  const pattern = /^[A-Z][A-D]\d{8}$/;
   if (!pattern.test(id)) {
     return false;
   }
 
-  const letter = id[0] as string;
-  const numbers = id.slice(1);
+  const firstLetter = id[0] as string;
+  const secondLetter = id[1] as string;
+  const numbers = id.slice(2);
 
-  const letterValue = LETTER_MAPPING[letter] as number;
+  const firstLetterValue = LETTER_MAPPING[firstLetter] as number;
+  const secondLetterValue = LETTER_MAPPING[secondLetter] as number;
 
-  // 計算檢查碼（與身分證字號相同的演算法）
-  const d1 = Math.floor(letterValue / 10);
-  const d2 = letterValue % 10;
+  const d1 = Math.floor(firstLetterValue / 10);
+  const d2 = firstLetterValue % 10;
+  const d3 = secondLetterValue % 10; // 取第二個字母對應數字的個位數
 
   const weights = [1, 9, 8, 7, 6, 5, 4, 3, 2, 1, 1];
-  const digits = [d1, d2, ...numbers.split("").map(Number)];
+  const digits = [d1, d2, d3, ...numbers.split("").map(Number)];
 
   const sum = digits.reduce(
     (acc, digit, index) => acc + digit * weights[index]!,
@@ -66,33 +37,28 @@ function validateOldFormat(id: string): boolean {
 }
 
 /**
- * 驗證新式居留證號格式（2個字母 + 8個數字）
- * 格式：AA12345678
+ * 驗證新式居留證號格式與檢查碼（1個字母 + 9個數字，其中第二碼為8或9）
+ * 格式：A800000001
  * - 第一個字元：地區代碼（字母）
- * - 第二個字元：性別（8 = 男性，9 = 女性）以字母表示
+ * - 第二個字元：性別（8 = 男性，9 = 女性）
  * - 最後一個字元：檢查碼
  */
 function validateNewFormat(id: string): boolean {
-  const pattern = /^[A-Z]{2}\d{8}$/;
+  const pattern = /^[A-Z][89]\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 letter = id[0] as string;
+  const numbers = id.slice(1);
 
-  const firstLetterValue = LETTER_MAPPING[firstLetter] as number;
-  const secondLetterValue = LETTER_MAPPING[secondLetter] as number;
+  const letterValue = LETTER_MAPPING[letter] as number;
 
-  // 計算新式格式的檢查碼
-  const d1 = Math.floor(firstLetterValue / 10);
-  const d2 = firstLetterValue % 10;
-  const d3 = Math.floor(secondLetterValue / 10);
-  const d4 = secondLetterValue % 10;
+  const d1 = Math.floor(letterValue / 10);
+  const d2 = letterValue % 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 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]!,
@@ -106,25 +72,25 @@ function validateNewFormat(id: string): boolean {
  * 偵測居留證號格式類型
  */
 function detectFormat(id: string): ResidentCertificateType | null {
-  if (/^[A-D][89]\d{8}$/.test(id)) {
+  if (/^[A-Z][A-D]\d{8}$/.test(id)) {
     return "old";
   }
-  if (/^[A-Z]{2}\d{8}$/.test(id)) {
+  if (/^[A-Z][89]\d{8}$/.test(id)) {
     return "new";
   }
   return null;
 }
 
 /**
- * 驗證台灣居留證號（支援新舊格式）
+ * 驗證台灣居留證號（支援新舊格式，舊版為2字母+8數字，新版為1字母+9數字）
  * @param id - 要驗證的居留證號
  * @param format - 可選：指定格式類型（'old' 或 'new'）
  * @returns 驗證結果
  *
  * @example
  * ```typescript
- * validateResidentCertificate('A800000000'); // 舊式格式
- * validateResidentCertificate('AA12345678'); // 新式格式
+ * validateResidentCertificate('AD00000001', 'old'); // 舊式格式
+ * validateResidentCertificate('A800000001', 'new'); // 新式格式
  * ```
  */
 export function validateResidentCertificate(
@@ -140,7 +106,6 @@ export function validateResidentCertificate(
 
   const normalizedId = id.trim().toUpperCase();
 
-  // 如果指定了格式，只驗證該格式
   if (format === "old") {
     const isValid = validateOldFormat(normalizedId);
     return {
@@ -157,7 +122,6 @@ export function validateResidentCertificate(
     };
   }
 
-  // 自動偵測格式
   const detectedFormat = detectFormat(normalizedId);
 
   if (!detectedFormat) {
@@ -179,3 +143,69 @@ export function validateResidentCertificate(
       : `無效的${detectedFormat === "old" ? "舊式" : "新式"}居留證號`,
   };
 }
+
+/**
+ * 解析台灣居留證號資訊（格式版本、性別、發證地區、身分類型）
+ * @param id - 要解析的居留證號
+ * @returns 解析結果，包含驗證狀態及相關欄位
+ *
+ * @example
+ * ```typescript
+ * parseResidentCertificate('A800000001');
+ * // 輸出: { isValid: true, format: 'new', gender: 'male', region: '臺北市' }
+ * ```
+ */
+export function parseResidentCertificate(id: string): ResidentCertificateInfo {
+  if (!id || typeof id !== "string") {
+    return {
+      isValid: false,
+      message: "居留證號必須為非空字串",
+    };
+  }
+
+  const normalizedId = id.trim().toUpperCase();
+
+  const format = detectFormat(normalizedId);
+  if (!format) {
+    return {
+      isValid: false,
+      message: "無效的居留證號格式",
+    };
+  }
+
+  const isValid =
+    format === "old"
+      ? validateOldFormat(normalizedId)
+      : validateNewFormat(normalizedId);
+
+  if (!isValid) {
+    return {
+      isValid: false,
+      message: `無效的${format === "old" ? "舊式" : "新式"}居留證號`,
+    };
+  }
+
+  const firstLetter = normalizedId[0] as string;
+  const secondChar = normalizedId[1] as string;
+
+  const region = REGION_MAPPING[firstLetter] as string;
+  let gender: "male" | "female";
+  let identityType: "non-citizen" | "foreigner" | undefined;
+
+  if (format === "new") {
+    gender = secondChar === "8" ? "male" : "female";
+    identityType = "foreigner"; // 新式格式下通常統稱為外來人口
+  } else {
+    // 舊式格式: A, B, C, D
+    gender = (secondChar === "A" || secondChar === "C") ? "male" : "female";
+    identityType = (secondChar === "A" || secondChar === "B") ? "non-citizen" : "foreigner";
+  }
+
+  return {
+    isValid: true,
+    format,
+    gender,
+    region,
+    identityType,
+  };
+}

package/src/validators/shared.ts

@@ -0,0 +1,63 @@
+/**
+ * 字母對應數字表（用於身分證字號與居留證號驗證）
+ */
+export 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,
+};
+
+/**
+ * 字母對應地區名稱表
+ */
+export const REGION_MAPPING: Record<string, string> = {
+  A: "臺北市",
+  B: "臺中市",
+  C: "基隆市",
+  D: "臺南市",
+  E: "高雄市",
+  F: "新北市",
+  G: "宜蘭縣",
+  H: "桃園市",
+  I: "嘉義市",
+  J: "新竹縣",
+  K: "苗栗縣",
+  L: "臺中縣",
+  M: "南投縣",
+  N: "彰化縣",
+  O: "新竹市",
+  P: "雲林縣",
+  Q: "嘉義縣",
+  R: "臺南縣",
+  S: "高雄縣",
+  T: "屏東縣",
+  U: "花蓮縣",
+  V: "臺東縣",
+  W: "金門縣",
+  X: "澎湖縣",
+  Y: "陽明山管理局",
+  Z: "連江縣",
+};

package/src/validators/uniform-invoice.test.ts

@@ -0,0 +1,24 @@
+import { validateUniformInvoice } from "./uniform-invoice";
+
+describe("validateUniformInvoice", () => {
+  test("should validate correct invoice numbers", () => {
+    expect(validateUniformInvoice("AB-12345678").isValid).toBe(true);
+    expect(validateUniformInvoice("ab-12345678").isValid).toBe(true);
+    expect(validateUniformInvoice("AB12345678").isValid).toBe(true);
+    expect(validateUniformInvoice("AB 12345678").isValid).toBe(true);
+  });
+
+  test("should reject invalid invoice numbers", () => {
+    expect(validateUniformInvoice("A-12345678").isValid).toBe(false); // Only 1 letter
+    expect(validateUniformInvoice("ABC-12345678").isValid).toBe(false); // 3 letters
+    expect(validateUniformInvoice("AB-1234567").isValid).toBe(false); // 7 digits
+    expect(validateUniformInvoice("AB-123456789").isValid).toBe(false); // 9 digits
+    expect(validateUniformInvoice("1234567890").isValid).toBe(false); // No letters
+  });
+
+  test("should reject empty or non-string inputs", () => {
+    expect(validateUniformInvoice("").isValid).toBe(false);
+    // @ts-expect-error Testing invalid input type
+    expect(validateUniformInvoice(null).isValid).toBe(false);
+  });
+});

package/src/validators/uniform-invoice.ts

@@ -0,0 +1,39 @@
+import type { ValidationResult } from "../types";
+
+/**
+ * 驗證台灣統一發票號碼格式
+ * 格式為 2 碼英文開頭 + 8 碼數字（可包含減號或空格，如 AB-12345678 或 AB 12345678）
+ *
+ * @param invoice - 要驗證的發票號碼
+ * @returns 驗證結果
+ *
+ * @example
+ * ```typescript
+ * validateUniformInvoice('AB-12345678'); // { isValid: true }
+ * validateUniformInvoice('AB12345678');  // { isValid: true }
+ * ```
+ */
+export function validateUniformInvoice(invoice: string): ValidationResult {
+  if (!invoice || typeof invoice !== "string") {
+    return {
+      isValid: false,
+      message: "發票號碼必須為非空字串",
+    };
+  }
+
+  // 去除空格與減號並轉大寫
+  const normalized = invoice.replace(/[-\s]/g, "").toUpperCase();
+
+  const pattern = /^[A-Z]{2}\d{8}$/;
+
+  if (!pattern.test(normalized)) {
+    return {
+      isValid: false,
+      message: "發票號碼格式必須為2碼英文與8碼數字",
+    };
+  }
+
+  return {
+    isValid: true,
+  };
+}