taiwan-validator 1.0.0 → 1.2.0

package/src/validators/license-plate.test.ts

@@ -0,0 +1,336 @@
+import { validateLicensePlate } from "./license-plate";
+
+describe("validateLicensePlate", () => {
+  describe("基本驗證", () => {
+    test("應該拒絕空字串", () => {
+      const result = validateLicensePlate("");
+      expect(result.isValid).toBe(false);
+      expect(result.message).toBe("車牌號碼必須為非空字串");
+    });
+
+    test("應該拒絕非字串輸入", () => {
+      const result = validateLicensePlate(null as unknown as string);
+      expect(result.isValid).toBe(false);
+      expect(result.message).toBe("車牌號碼必須為非空字串");
+    });
+
+    test("應該拒絕無效的格式", () => {
+      const result = validateLicensePlate("INVALID");
+      expect(result.isValid).toBe(false);
+      expect(result.message).toBe("無效的車牌號碼格式");
+    });
+
+    test("應該處理小寫輸入並轉換為大寫", () => {
+      const result = validateLicensePlate("abc-1235");
+      expect(result.isValid).toBe(true);
+      expect(result.plateType).toBe("car");
+    });
+
+    test("應該處理含有空格的輸入", () => {
+      const result = validateLicensePlate(" ABC-1235 ");
+      expect(result.isValid).toBe(true);
+      expect(result.plateType).toBe("car");
+    });
+  });
+
+  describe("新制汽車車牌驗證", () => {
+    test("應該驗證有效的新制汽車車牌", () => {
+      const validPlates = [
+        "ABC-1235",
+        "XYZ-9876",
+        "AAA-0000",
+        "ZZZ-9999",
+        "ABC-1230",
+      ];
+
+      validPlates.forEach((plate) => {
+        const result = validateLicensePlate(plate);
+        expect(result.isValid).toBe(true);
+        expect(result.plateType).toBe("car");
+      });
+    });
+
+    test("應該拒絕包含數字4的車牌", () => {
+      const invalidPlates = [
+        "ABC-1234", // 包含4
+        "ABC-4567", // 包含4
+        "ABC-0004", // 包含4
+      ];
+
+      invalidPlates.forEach((plate) => {
+        const result = validateLicensePlate(plate);
+        expect(result.isValid).toBe(false);
+      });
+    });
+
+    test("應該拒絕包含字母I或O的車牌", () => {
+      const invalidPlates = [
+        "AIC-1235", // 包含I
+        "AOC-1235", // 包含O
+        "IBC-1235", // 包含I
+        "OBC-1235", // 包含O
+      ];
+
+      invalidPlates.forEach((plate) => {
+        const result = validateLicensePlate(plate);
+        expect(result.isValid).toBe(false);
+      });
+    });
+
+    test("應該拒絕格式錯誤的汽車車牌（指定類型驗證）", () => {
+      const invalidPlates = [
+        "AB-1235", // 只有2個字母
+        "ABCD-1235", // 4個字母
+        "ABC-123", // 只有3個數字（但這是有效的小型機車格式）
+        "ABC-12345", // 5個數字
+        "ABC1235", // 缺少破折號
+      ];
+
+      invalidPlates.forEach((plate) => {
+        const result = validateLicensePlate(plate, { type: "car" });
+        expect(result.isValid).toBe(false);
+      });
+    });
+
+    test("當指定類型為car時，應該只驗證新制汽車格式", () => {
+      const result = validateLicensePlate("ABC-1235", { type: "car" });
+      expect(result.isValid).toBe(true);
+      expect(result.plateType).toBe("car");
+    });
+
+    test("當指定類型為car但格式錯誤時，應該返回錯誤訊息", () => {
+      const result = validateLicensePlate("1A-2345", { type: "car" });
+      expect(result.isValid).toBe(false);
+      expect(result.message).toBe("無效的汽車車牌號碼");
+    });
+  });
+
+  describe("舊制汽車車牌驗證", () => {
+    test("應該驗證有效的舊制汽車車牌", () => {
+      const validPlates = ["1A-2345", "9Z-0000", "5B-9999", "3X-1234"];
+
+      validPlates.forEach((plate) => {
+        const result = validateLicensePlate(plate);
+        expect(result.isValid).toBe(true);
+        expect(result.plateType).toBe("car-old");
+      });
+    });
+
+    test("應該拒絕格式錯誤的舊制車牌", () => {
+      const invalidPlates = [
+        "AA-2345", // 2個字母
+        "1AB-2345", // 2個字母
+        "1-2345", // 缺少字母
+        "1A-234", // 只有3個數字
+        "1A-23456", // 5個數字
+      ];
+
+      invalidPlates.forEach((plate) => {
+        const result = validateLicensePlate(plate);
+        expect(result.isValid).toBe(false);
+      });
+    });
+
+    test("當指定類型為car-old時，應該只驗證舊制汽車格式", () => {
+      const result = validateLicensePlate("1A-2345", { type: "car-old" });
+      expect(result.isValid).toBe(true);
+      expect(result.plateType).toBe("car-old");
+    });
+  });
+
+  describe("電動汽車車牌驗證", () => {
+    test("應該驗證有效的電動汽車車牌", () => {
+      const validPlates = [
+        "EAB-1235",
+        "EXY-9876",
+        "EAA-0000",
+        "EZZ-9999",
+        "EAB-1230",
+      ];
+
+      validPlates.forEach((plate) => {
+        const result = validateLicensePlate(plate);
+        expect(result.isValid).toBe(true);
+        expect(result.plateType).toBe("electric-car");
+      });
+    });
+
+    test("應該拒絕包含數字4的電動車牌", () => {
+      const invalidPlates = ["EAB-1234", "EAB-4567", "EAB-0004"];
+
+      invalidPlates.forEach((plate) => {
+        const result = validateLicensePlate(plate);
+        expect(result.isValid).toBe(false);
+      });
+    });
+
+    test("應該拒絕包含字母I或O的電動車牌", () => {
+      const invalidPlates = [
+        "EIC-1235", // 包含I
+        "EOC-1235", // 包含O
+        "EIA-1235", // 包含I
+        "EOA-1235", // 包含O
+      ];
+
+      invalidPlates.forEach((plate) => {
+        const result = validateLicensePlate(plate);
+        expect(result.isValid).toBe(false);
+      });
+    });
+
+    test("應該拒絕不以E開頭的電動車牌", () => {
+      const invalidPlates = ["AAB-1235", "XAB-1235"];
+
+      invalidPlates.forEach((plate) => {
+        const result = validateLicensePlate(plate);
+        expect(result.plateType).not.toBe("electric-car");
+      });
+    });
+
+    test("當指定類型為electric-car時，應該只驗證電動汽車格式", () => {
+      const result = validateLicensePlate("EAB-1235", {
+        type: "electric-car",
+      });
+      expect(result.isValid).toBe(true);
+      expect(result.plateType).toBe("electric-car");
+    });
+  });
+
+  describe("小型機車車牌驗證", () => {
+    test("應該驗證有效的小型機車車牌（數字-字母格式）", () => {
+      const validPlates = ["123-ABC", "000-ZZZ", "999-AAA", "456-XYZ"];
+
+      validPlates.forEach((plate) => {
+        const result = validateLicensePlate(plate);
+        expect(result.isValid).toBe(true);
+        expect(result.plateType).toBe("motorcycle-small");
+      });
+    });
+
+    test("應該驗證有效的小型機車車牌（字母-數字格式）", () => {
+      const validPlates = ["ABC-123", "ZZZ-000", "AAA-999", "XYZ-456"];
+
+      validPlates.forEach((plate) => {
+        const result = validateLicensePlate(plate);
+        expect(result.isValid).toBe(true);
+        expect(result.plateType).toBe("motorcycle-small");
+      });
+    });
+
+    test("應該拒絕格式錯誤的小型機車車牌", () => {
+      const invalidPlates = [
+        "12-ABC", // 只有2個數字
+        "1234-ABC", // 4個數字
+        "123-AB", // 只有2個字母
+        "123-ABCD", // 4個字母
+        "AB-123", // 字母只有2個
+      ];
+
+      invalidPlates.forEach((plate) => {
+        const result = validateLicensePlate(plate);
+        expect(result.plateType).not.toBe("motorcycle-small");
+      });
+    });
+
+    test("當指定類型為motorcycle-small時，應該只驗證小型機車格式", () => {
+      const result1 = validateLicensePlate("123-ABC", {
+        type: "motorcycle-small",
+      });
+      expect(result1.isValid).toBe(true);
+      expect(result1.plateType).toBe("motorcycle-small");
+
+      const result2 = validateLicensePlate("ABC-123", {
+        type: "motorcycle-small",
+      });
+      expect(result2.isValid).toBe(true);
+      expect(result2.plateType).toBe("motorcycle-small");
+    });
+  });
+
+  describe("一般機車車牌驗證", () => {
+    test("應該驗證有效的一般機車車牌", () => {
+      const validPlates = ["AB1-234", "XY9-000", "ZZ0-999", "AA5-123"];
+
+      validPlates.forEach((plate) => {
+        const result = validateLicensePlate(plate);
+        expect(result.isValid).toBe(true);
+        expect(result.plateType).toBe("motorcycle");
+      });
+    });
+
+    test("應該拒絕格式錯誤的一般機車車牌", () => {
+      const invalidPlates = [
+        "A1-234", // 只有1個字母
+        "ABC1-234", // 3個字母
+        "AB-234", // 缺少數字
+        "AB12-234", // 2個數字
+        "AB1-23", // 只有2個數字
+        "AB1-2345", // 4個數字
+      ];
+
+      invalidPlates.forEach((plate) => {
+        const result = validateLicensePlate(plate);
+        expect(result.plateType).not.toBe("motorcycle");
+      });
+    });
+
+    test("當指定類型為motorcycle時，應該只驗證一般機車格式", () => {
+      const result = validateLicensePlate("AB1-234", { type: "motorcycle" });
+      expect(result.isValid).toBe(true);
+      expect(result.plateType).toBe("motorcycle");
+    });
+  });
+
+  describe("車牌類型偵測選項", () => {
+    test("當 detectType 為 false 時，不應該回傳 plateType", () => {
+      const result = validateLicensePlate("ABC-1235", { detectType: false });
+      expect(result.isValid).toBe(true);
+      expect(result.plateType).toBeUndefined();
+    });
+
+    test("當 detectType 為 true 時，應該回傳 plateType", () => {
+      const result = validateLicensePlate("ABC-1235", { detectType: true });
+      expect(result.isValid).toBe(true);
+      expect(result.plateType).toBe("car");
+    });
+
+    test("預設應該偵測車牌類型", () => {
+      const result = validateLicensePlate("ABC-1235");
+      expect(result.isValid).toBe(true);
+      expect(result.plateType).toBe("car");
+    });
+
+    test("當指定類型且 detectType 為 false 時，不應該回傳 plateType", () => {
+      const result = validateLicensePlate("ABC-1235", {
+        type: "car",
+        detectType: false,
+      });
+      expect(result.isValid).toBe(true);
+      expect(result.plateType).toBeUndefined();
+    });
+  });
+
+  describe("類型優先順序測試", () => {
+    test("應該優先識別為電動汽車而非一般汽車", () => {
+      const result = validateLicensePlate("EAB-1235");
+      expect(result.isValid).toBe(true);
+      expect(result.plateType).toBe("electric-car");
+    });
+
+    test("應該正確區分新制和舊制汽車", () => {
+      const newCar = validateLicensePlate("ABC-1235");
+      expect(newCar.plateType).toBe("car");
+
+      const oldCar = validateLicensePlate("1A-2345");
+      expect(oldCar.plateType).toBe("car-old");
+    });
+
+    test("應該正確區分小型機車和一般機車", () => {
+      const smallMotorcycle = validateLicensePlate("123-ABC");
+      expect(smallMotorcycle.plateType).toBe("motorcycle-small");
+
+      const motorcycle = validateLicensePlate("AB1-234");
+      expect(motorcycle.plateType).toBe("motorcycle");
+    });
+  });
+});

package/src/validators/license-plate.ts

@@ -0,0 +1,215 @@
+import type { ValidationResult } from "../types";
+
+/**
+ * 車牌類型
+ */
+export type LicensePlateType =
+  | "car" // 汽車（新制）
+  | "car-old" // 汽車（舊制）
+  | "electric-car" // 電動汽車
+  | "motorcycle-small" // 小型機車（50cc以下）
+  | "motorcycle"; // 一般機車
+
+/**
+ * 車牌驗證結果（含車牌類型資訊）
+ */
+export interface LicensePlateValidationResult extends ValidationResult {
+  plateType?: LicensePlateType | undefined;
+}
+
+/**
+ * 驗證新制汽車車牌（2012年12月後）
+ * 格式：3個英文字母 - 4個數字
+ * 不使用字母 I、O
+ * 不使用數字 4
+ */
+function validateNewCarPlate(plate: string): boolean {
+  // 格式：3個英文字母-4個數字（例如：ABC-1234）
+  const pattern = /^[A-HJ-NP-Z]{3}-\d{4}$/;
+  if (!pattern.test(plate)) {
+    return false;
+  }
+
+  // 檢查數字部分不包含 4
+  const numbers = plate.split("-")[1] as string;
+  return !numbers.includes("4");
+}
+
+/**
+ * 驗證舊制汽車車牌（1992-2012）
+ * 格式：1個數字 + 1個英文字母 - 4個數字
+ */
+function validateOldCarPlate(plate: string): boolean {
+  // 格式：1個數字+1個英文字母-4個數字（例如：1A-2345）
+  const pattern = /^\d[A-Z]-\d{4}$/;
+  return pattern.test(plate);
+}
+
+/**
+ * 驗證電動汽車車牌
+ * 格式：E + 2個英文字母 - 4個數字
+ * 不使用字母 I、O
+ * 不使用數字 4
+ */
+function validateElectricCarPlate(plate: string): boolean {
+  // 格式：E + 2個英文字母-4個數字（例如：EAB-1234）
+  const pattern = /^E[A-HJ-NP-Z]{2}-\d{4}$/;
+  if (!pattern.test(plate)) {
+    return false;
+  }
+
+  // 檢查數字部分不包含 4
+  const numbers = plate.split("-")[1] as string;
+  return !numbers.includes("4");
+}
+
+/**
+ * 驗證小型機車車牌（50cc以下）
+ * 格式：3個數字-3個英文字母 或 3個英文字母-3個數字
+ */
+function validateSmallMotorcyclePlate(plate: string): boolean {
+  // 格式1：3個數字-3個英文字母（例如：123-ABC）
+  // 格式2：3個英文字母-3個數字（例如：ABC-123）
+  const pattern1 = /^\d{3}-[A-Z]{3}$/;
+  const pattern2 = /^[A-Z]{3}-\d{3}$/;
+  return pattern1.test(plate) || pattern2.test(plate);
+}
+
+/**
+ * 驗證一般機車車牌（舊制，50-250cc）
+ * 格式：2個英文字母 + 1個數字 - 3個數字
+ */
+function validateMotorcyclePlate(plate: string): boolean {
+  // 格式：2個英文字母+1個數字-3個數字（例如：AB1-234）
+  const pattern = /^[A-Z]{2}\d-\d{3}$/;
+  return pattern.test(plate);
+}
+
+/**
+ * 偵測車牌類型
+ */
+function detectPlateType(plate: string): LicensePlateType | null {
+  if (validateElectricCarPlate(plate)) {
+    return "electric-car";
+  }
+  if (validateNewCarPlate(plate)) {
+    return "car";
+  }
+  if (validateOldCarPlate(plate)) {
+    return "car-old";
+  }
+  if (validateSmallMotorcyclePlate(plate)) {
+    return "motorcycle-small";
+  }
+  if (validateMotorcyclePlate(plate)) {
+    return "motorcycle";
+  }
+  return null;
+}
+
+/**
+ * 驗證台灣車牌號碼
+ * @param plate - 要驗證的車牌號碼
+ * @param options - 驗證選項
+ * @param options.type - 可選：指定車牌類型
+ * @param options.detectType - 是否偵測車牌類型（預設：true）
+ * @returns 驗證結果
+ *
+ * @example
+ * ```typescript
+ * // 新制汽車
+ * validateLicensePlate('ABC-1235');
+ *
+ * // 電動汽車
+ * validateLicensePlate('EAB-1235');
+ *
+ * // 舊制汽車
+ * validateLicensePlate('1A-2345');
+ *
+ * // 小型機車
+ * validateLicensePlate('123-ABC');
+ * validateLicensePlate('ABC-123');
+ *
+ * // 一般機車
+ * validateLicensePlate('AB1-234');
+ *
+ * // 指定類型驗證
+ * validateLicensePlate('ABC-1235', { type: 'car' });
+ *
+ * // 不偵測類型
+ * validateLicensePlate('ABC-1235', { detectType: false });
+ * ```
+ */
+export function validateLicensePlate(
+  plate: string,
+  options: { type?: LicensePlateType; detectType?: boolean } = {},
+): LicensePlateValidationResult {
+  const { type, detectType = true } = options;
+
+  if (!plate || typeof plate !== "string") {
+    return {
+      isValid: false,
+      message: "車牌號碼必須為非空字串",
+    };
+  }
+
+  // 移除空格並轉換為大寫
+  const normalized = plate.trim().toUpperCase();
+
+  // 如果指定了類型，只驗證該類型
+  if (type) {
+    let isValid = false;
+    switch (type) {
+      case "car":
+        isValid = validateNewCarPlate(normalized);
+        break;
+      case "car-old":
+        isValid = validateOldCarPlate(normalized);
+        break;
+      case "electric-car":
+        isValid = validateElectricCarPlate(normalized);
+        break;
+      case "motorcycle-small":
+        isValid = validateSmallMotorcyclePlate(normalized);
+        break;
+      case "motorcycle":
+        isValid = validateMotorcyclePlate(normalized);
+        break;
+    }
+
+    return {
+      isValid,
+      message: isValid ? undefined : `無效的${getPlateTypeName(type)}車牌號碼`,
+      plateType: isValid && detectType ? type : undefined,
+    };
+  }
+
+  // 自動偵測類型
+  const detectedType = detectPlateType(normalized);
+
+  if (!detectedType) {
+    return {
+      isValid: false,
+      message: "無效的車牌號碼格式",
+    };
+  }
+
+  return {
+    isValid: true,
+    plateType: detectType ? detectedType : undefined,
+  };
+}
+
+/**
+ * 取得車牌類型的中文名稱
+ */
+function getPlateTypeName(type: LicensePlateType): string {
+  const typeNames: Record<LicensePlateType, string> = {
+    car: "汽車",
+    "car-old": "汽車（舊制）",
+    "electric-car": "電動汽車",
+    "motorcycle-small": "小型機車",
+    motorcycle: "機車",
+  };
+  return typeNames[type];
+}

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

@@ -1,78 +1,51 @@
-import { validateNationalId } from "./national-id";
+import { validateNationalId, parseNationalId } from "./national-id";
 
 describe("validateNationalId", () => {
-  describe("Old Format", () => {
-    test("should validate correct old format National IDs", () => {
+  describe("Validation", () => {
+    test("should validate correct 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);
+      expect(validateNationalId("A123456789").isValid).toBe(true);
+      expect(validateNationalId("F223456786").isValid).toBe(true);
+      expect(validateNationalId("O123456782").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 reject invalid National IDs", () => {
+      expect(validateNationalId("A123456788").isValid).toBe(false); // Wrong checksum
+      expect(validateNationalId("A323456789").isValid).toBe(false); // Invalid gender code
+      expect(validateNationalId("A12345678").isValid).toBe(false); // Too short
+      expect(validateNationalId("A1234567890").isValid).toBe(false); // Too long
+      expect(validateNationalId("AA23456786").isValid).toBe(false); // 2-letter legacy format is not a National ID
     });
 
     test("should handle case insensitive input", () => {
-      expect(validateNationalId("aa23456786", "new").isValid).toBe(true);
+      expect(validateNationalId("a123456789").isValid).toBe(true);
+      expect(validateNationalId("f223456786").isValid).toBe(true);
     });
 
     test("should handle whitespace", () => {
-      expect(validateNationalId(" AB23456789 ", "new").isValid).toBe(true);
+      expect(validateNationalId(" A123456789 ").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("無效的新式身分證字號");
+  describe("Parser (parseNationalId)", () => {
+    test("should parse correct National IDs with gender and region", () => {
+      const parsed1 = parseNationalId("A123456789");
+      expect(parsed1.isValid).toBe(true);
+      expect(parsed1.gender).toBe("male");
+      expect(parsed1.region).toBe("臺北市");
+
+      const parsed2 = parseNationalId("F223456786");
+      expect(parsed2.isValid).toBe(true);
+      expect(parsed2.gender).toBe("female");
+      expect(parsed2.region).toBe("新北市");
     });
 
-    test("should reject completely invalid formats", () => {
-      expect(validateNationalId("12345678").isValid).toBe(false);
-      expect(validateNationalId("ABCDEFGH").isValid).toBe(false);
+    test("should return isValid: false for invalid IDs", () => {
+      const parsed = parseNationalId("A123456788");
+      expect(parsed.isValid).toBe(false);
+      expect(parsed.gender).toBeUndefined();
+      expect(parsed.region).toBeUndefined();
+      expect(parsed.message).toBe("無效的身分證字號");
     });
   });
 
@@ -87,9 +60,9 @@ describe("validateNationalId", () => {
     });
 
     test("should provide meaningful error messages", () => {
-      const result1 = validateNationalId("A123456788", "old");
+      const result1 = validateNationalId("A123456788");
       expect(result1.isValid).toBe(false);
-      expect(result1.message).toBeDefined();
+      expect(result1.message).toBe("無效的身分證字號");
 
       const result2 = validateNationalId("");
       expect(result2.isValid).toBe(false);