taiwan-validator 1.0.0

package/package.json

@@ -0,0 +1,128 @@
+{
+  "name": "taiwan-validator",
+  "version": "1.0.0",
+  "description": "A comprehensive validator for Taiwan identification numbers and codes (身分證字號、統一編號、居留證號、手機號碼、自然人憑證、電子發票條碼)",
+  "license": "MIT",
+  "author": "Gary Lai <garylai1990@gmail.com>",
+  "homepage": "https://github.com/imgarylai/taiwan-validator#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/imgarylai/taiwan-validator.git"
+  },
+  "bugs": {
+    "url": "https://github.com/imgarylai/taiwan-validator/issues"
+  },
+  "type": "module",
+  "exports": {
+    "types": "./dist/index.d.ts",
+    "import": "./dist/index.mjs",
+    "require": "./dist/index.cjs"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rimraf dist coverage",
+    "dev": "tsup --watch",
+    "predocs": "rimraf docs",
+    "docs": "typedoc",
+    "docs:watch": "typedoc --watch",
+    "lint": "eslint .",
+    "prepack": "npm run build",
+    "prepare": "husky",
+    "test": "jest",
+    "test:coverage": "jest --coverage",
+    "type-check": "tsc --noEmit"
+  },
+  "config": {
+    "commitizen": {
+      "path": "./node_modules/cz-conventional-changelog"
+    }
+  },
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@semantic-release/changelog": "^6.0.0",
+    "@semantic-release/commit-analyzer": "^13.0.0",
+    "@semantic-release/git": "^10.0.0",
+    "@semantic-release/npm": "^13.0.0",
+    "@semantic-release/release-notes-generator": "^14.0.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "cz-conventional-changelog": "3.3.0",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^10.0.0",
+    "eslint-plugin-jest": "29.12.1",
+    "husky": "9.1.7",
+    "jest": "^30.0.0",
+    "lint-staged": "16.2.7",
+    "prettier": "^3.2.5",
+    "prettier-package-json": "^2.4.11",
+    "rimraf": "^6.0.0",
+    "semantic-release": "^25.0.0",
+    "sort-package-json": "3.6.0",
+    "ts-jest": "^29.1.2",
+    "tsup": "^8.0.2",
+    "typedoc": "^0.28.2",
+    "typescript": "5.9.3"
+  },
+  "keywords": [
+    "business-number",
+    "citizen-certificate",
+    "einvoice",
+    "id",
+    "identification",
+    "mobile-phone",
+    "national-id",
+    "resident-certificate",
+    "taiwan",
+    "validation",
+    "validator",
+    "台灣",
+    "居留證",
+    "手機",
+    "統一編號",
+    "自然人憑證",
+    "身分證",
+    "電子發票",
+    "驗證"
+  ],
+  "engines": {
+    "node": ">=22.0.0",
+    "npm": ">=10.0.0"
+  },
+  "lint-staged": {
+    "*.{js,jsx,ts,tsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "src/**/*.{js,jsx,ts,tsx}": [
+      "jest --bail --findRelatedTests"
+    ],
+    "*.{json,md}": [
+      "prettier --write"
+    ],
+    "package.json": [
+      "prettier-package-json --write"
+    ]
+  },
+  "release": {
+    "branches": [
+      "main"
+    ],
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      "@semantic-release/changelog",
+      "@semantic-release/npm",
+      "@semantic-release/git"
+    ]
+  }
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Taiwan Validator - 台灣驗證器
+ * 提供完整的台灣身分證件和代碼驗證功能，包括：
+ * - 身分證字號
+ * - 營利事業統一編號
+ * - 居留證號
+ * - 手機號碼
+ * - 自然人憑證
+ * - 電子發票手機條碼
+ * - 電子發票捐贈碼
+ */
+
+export { validateNationalId } from "./validators/national-id";
+export { validateBusinessNumber } from "./validators/business-number";
+export { validateResidentCertificate } from "./validators/resident-certificate";
+export { validateMobilePhone } from "./validators/mobile-phone";
+export { validateCitizenCertificate } from "./validators/citizen-certificate";
+export { validateEInvoiceMobileBarcode } from "./validators/einvoice-mobile-barcode";
+export { validateEInvoiceDonationCode } from "./validators/einvoice-donation-code";
+
+export type {
+  ValidationResult,
+  Gender,
+  NationalIdType,
+  ResidentCertificateType,
+} from "./types";

package/src/types.ts

@@ -0,0 +1,22 @@
+/**
+ * 驗證結果介面
+ */
+export interface ValidationResult {
+  isValid: boolean;
+  message?: string | undefined;
+}
+
+/**
+ * 身分證字號性別類型
+ */
+export type Gender = "male" | "female";
+
+/**
+ * 居留證類型
+ */
+export type ResidentCertificateType = "old" | "new";
+
+/**
+ * 身分證字號類型
+ */
+export type NationalIdType = "old" | "new";

package/src/validators/business-number.test.ts

@@ -0,0 +1,63 @@
+import { validateBusinessNumber } from "./business-number";
+
+describe("validateBusinessNumber", () => {
+  describe("Valid Business Numbers", () => {
+    test("should validate correct business numbers", () => {
+      expect(validateBusinessNumber("12345676").isValid).toBe(true);
+      expect(validateBusinessNumber("53212539").isValid).toBe(true);
+      expect(validateBusinessNumber("04595257").isValid).toBe(true);
+    });
+
+    test("should validate business numbers with 7th digit = 7 (special case)", () => {
+      // When 7th digit is 7, sum % 10 can be 0 or 1
+      expect(validateBusinessNumber("12345676").isValid).toBe(true);
+      expect(validateBusinessNumber("12345677").isValid).toBe(true);
+    });
+  });
+
+  describe("Invalid Business Numbers", () => {
+    test("should reject invalid business numbers", () => {
+      expect(validateBusinessNumber("12345670").isValid).toBe(false); // Wrong checksum
+      expect(validateBusinessNumber("12345671").isValid).toBe(false); // Wrong checksum
+    });
+
+    test("should reject incorrect length", () => {
+      expect(validateBusinessNumber("1234567").isValid).toBe(false); // Too short
+      expect(validateBusinessNumber("123456789").isValid).toBe(false); // Too long
+    });
+
+    test("should reject non-numeric input", () => {
+      expect(validateBusinessNumber("1234567A").isValid).toBe(false);
+      expect(validateBusinessNumber("ABCDEFGH").isValid).toBe(false);
+    });
+  });
+
+  describe("Edge Cases", () => {
+    test("should handle whitespace", () => {
+      expect(validateBusinessNumber(" 12345676 ").isValid).toBe(true);
+    });
+
+    test("should reject empty or invalid input", () => {
+      expect(validateBusinessNumber("").isValid).toBe(false);
+      expect(validateBusinessNumber("   ").isValid).toBe(false);
+      // @ts-expect-error Testing invalid input type
+      expect(validateBusinessNumber(null).isValid).toBe(false);
+      // @ts-expect-error Testing invalid input type
+      expect(validateBusinessNumber(undefined).isValid).toBe(false);
+    });
+
+    test("should provide meaningful error messages", () => {
+      const result1 = validateBusinessNumber("1234567");
+      expect(result1.isValid).toBe(false);
+      expect(result1.message).toBe("統一編號必須為8位數字");
+
+      const result2 = validateBusinessNumber("12345670");
+      expect(result2.isValid).toBe(false);
+      expect(result2.message).toBe("統一編號檢查碼錯誤");
+
+      const result3 = validateBusinessNumber("");
+      expect(result3.isValid).toBe(false);
+      expect(result3.message).toBe("統一編號必須為非空字串");
+    });
+  });
+});

package/src/validators/business-number.ts

@@ -0,0 +1,59 @@
+import type { ValidationResult } from "../types";
+
+/**
+ * 驗證台灣營利事業統一編號
+ * 格式：8位數字
+ * 使用加權檢查碼演算法
+ *
+ * @param number - 要驗證的統一編號
+ * @returns 驗證結果
+ *
+ * @example
+ * ```typescript
+ * validateBusinessNumber('12345678');
+ * ```
+ */
+export function validateBusinessNumber(number: string): ValidationResult {
+  if (!number || typeof number !== "string") {
+    return {
+      isValid: false,
+      message: "統一編號必須為非空字串",
+    };
+  }
+
+  const normalized = number.trim();
+
+  // 檢查是否為8位數字
+  const pattern = /^\d{8}$/;
+  if (!pattern.test(normalized)) {
+    return {
+      isValid: false,
+      message: "統一編號必須為8位數字",
+    };
+  }
+
+  const digits = normalized.split("").map(Number);
+  const weights = [1, 2, 1, 2, 1, 2, 4, 1];
+
+  // 計算加權總和
+  let sum = 0;
+  for (let i = 0; i < 8; i++) {
+    let product = digits[i]! * weights[i]!;
+
+    // 如果乘積為兩位數，將十位數和個位數相加
+    if (product >= 10) {
+      product = Math.floor(product / 10) + (product % 10);
+    }
+
+    sum += product;
+  }
+
+  // 特殊情況：第7位數字為7時
+  // 如果第7位數字為7且總和除以10的餘數為1，也視為有效
+  const isValid = sum % 10 === 0 || (digits[6]! === 7 && sum % 10 === 1);
+
+  return {
+    isValid,
+    message: isValid ? undefined : "統一編號檢查碼錯誤",
+  };
+}

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

@@ -0,0 +1,73 @@
+import { validateCitizenCertificate } from "./citizen-certificate";
+
+describe("validateCitizenCertificate", () => {
+  describe("Valid Citizen Certificates", () => {
+    test("should validate correct citizen certificate numbers", () => {
+      expect(validateCitizenCertificate("AB12345678901234").isValid).toBe(true);
+      expect(validateCitizenCertificate("CD98765432109876").isValid).toBe(true);
+      expect(validateCitizenCertificate("XY11111111111111").isValid).toBe(true);
+    });
+
+    test("should handle case insensitive input", () => {
+      expect(validateCitizenCertificate("ab12345678901234").isValid).toBe(true);
+      expect(validateCitizenCertificate("Ab12345678901234").isValid).toBe(true);
+    });
+
+    test("should handle whitespace", () => {
+      expect(validateCitizenCertificate(" AB12345678901234 ").isValid).toBe(
+        true,
+      );
+    });
+  });
+
+  describe("Invalid Citizen Certificates", () => {
+    test("should reject incorrect length", () => {
+      expect(validateCitizenCertificate("AB1234567890123").isValid).toBe(false); // Too short
+      expect(validateCitizenCertificate("AB123456789012345").isValid).toBe(
+        false,
+      ); // Too long
+    });
+
+    test("should reject incorrect format", () => {
+      expect(validateCitizenCertificate("A12345678901234").isValid).toBe(false); // Only 1 letter
+      expect(validateCitizenCertificate("ABC1234567890123").isValid).toBe(
+        false,
+      ); // 3 letters
+      expect(validateCitizenCertificate("1212345678901234").isValid).toBe(
+        false,
+      ); // Starts with digits
+    });
+
+    test("should reject non-alphanumeric characters", () => {
+      expect(validateCitizenCertificate("AB-1234567890123").isValid).toBe(
+        false,
+      );
+      expect(validateCitizenCertificate("AB 1234567890123").isValid).toBe(
+        false,
+      );
+    });
+  });
+
+  describe("Edge Cases", () => {
+    test("should reject empty or invalid input", () => {
+      expect(validateCitizenCertificate("").isValid).toBe(false);
+      expect(validateCitizenCertificate("   ").isValid).toBe(false);
+      // @ts-expect-error Testing invalid input type
+      expect(validateCitizenCertificate(null).isValid).toBe(false);
+      // @ts-expect-error Testing invalid input type
+      expect(validateCitizenCertificate(undefined).isValid).toBe(false);
+    });
+
+    test("should provide meaningful error messages", () => {
+      const result1 = validateCitizenCertificate("AB123");
+      expect(result1.isValid).toBe(false);
+      expect(result1.message).toBe(
+        "自然人憑證編號必須為2個英文字母加上14位數字",
+      );
+
+      const result2 = validateCitizenCertificate("");
+      expect(result2.isValid).toBe(false);
+      expect(result2.message).toBe("自然人憑證編號必須為非空字串");
+    });
+  });
+});

package/src/validators/citizen-certificate.ts

@@ -0,0 +1,41 @@
+import type { ValidationResult } from "../types";
+
+/**
+ * 驗證台灣自然人憑證編號
+ * 格式：2個大寫英文字母 + 14位數字
+ * 範例：AB12345678901234
+ *
+ * @param certNumber - 要驗證的自然人憑證編號
+ * @returns 驗證結果
+ *
+ * @example
+ * ```typescript
+ * validateCitizenCertificate('AB12345678901234');
+ * ```
+ */
+export function validateCitizenCertificate(
+  certNumber: string,
+): ValidationResult {
+  if (!certNumber || typeof certNumber !== "string") {
+    return {
+      isValid: false,
+      message: "自然人憑證編號必須為非空字串",
+    };
+  }
+
+  const normalized = certNumber.trim().toUpperCase();
+
+  // 檢查格式：2個字母 + 14位數字
+  const pattern = /^[A-Z]{2}\d{14}$/;
+
+  if (!pattern.test(normalized)) {
+    return {
+      isValid: false,
+      message: "自然人憑證編號必須為2個英文字母加上14位數字",
+    };
+  }
+
+  return {
+    isValid: true,
+  };
+}

package/src/validators/einvoice-donation-code.test.ts

@@ -0,0 +1,78 @@
+import { validateEInvoiceDonationCode } from "./einvoice-donation-code";
+
+describe("validateEInvoiceDonationCode", () => {
+  describe("Valid Donation Codes", () => {
+    test("should validate 3-digit donation codes", () => {
+      expect(validateEInvoiceDonationCode("123").isValid).toBe(true);
+      expect(validateEInvoiceDonationCode("000").isValid).toBe(true);
+      expect(validateEInvoiceDonationCode("999").isValid).toBe(true);
+    });
+
+    test("should validate 4-digit donation codes", () => {
+      expect(validateEInvoiceDonationCode("1234").isValid).toBe(true);
+      expect(validateEInvoiceDonationCode("0000").isValid).toBe(true);
+      expect(validateEInvoiceDonationCode("9999").isValid).toBe(true);
+    });
+
+    test("should validate 5-digit donation codes", () => {
+      expect(validateEInvoiceDonationCode("12345").isValid).toBe(true);
+      expect(validateEInvoiceDonationCode("00000").isValid).toBe(true);
+      expect(validateEInvoiceDonationCode("99999").isValid).toBe(true);
+    });
+
+    test("should validate 6-digit donation codes", () => {
+      expect(validateEInvoiceDonationCode("123456").isValid).toBe(true);
+      expect(validateEInvoiceDonationCode("000000").isValid).toBe(true);
+      expect(validateEInvoiceDonationCode("999999").isValid).toBe(true);
+    });
+
+    test("should validate 7-digit donation codes", () => {
+      expect(validateEInvoiceDonationCode("1234567").isValid).toBe(true);
+      expect(validateEInvoiceDonationCode("0000000").isValid).toBe(true);
+      expect(validateEInvoiceDonationCode("9999999").isValid).toBe(true);
+    });
+
+    test("should handle whitespace", () => {
+      expect(validateEInvoiceDonationCode(" 12345 ").isValid).toBe(true);
+    });
+  });
+
+  describe("Invalid Donation Codes", () => {
+    test("should reject codes shorter than 3 digits", () => {
+      expect(validateEInvoiceDonationCode("12").isValid).toBe(false);
+      expect(validateEInvoiceDonationCode("1").isValid).toBe(false);
+    });
+
+    test("should reject codes longer than 7 digits", () => {
+      expect(validateEInvoiceDonationCode("12345678").isValid).toBe(false);
+      expect(validateEInvoiceDonationCode("123456789").isValid).toBe(false);
+    });
+
+    test("should reject non-numeric codes", () => {
+      expect(validateEInvoiceDonationCode("12A").isValid).toBe(false);
+      expect(validateEInvoiceDonationCode("ABC").isValid).toBe(false);
+      expect(validateEInvoiceDonationCode("12-34").isValid).toBe(false);
+    });
+  });
+
+  describe("Edge Cases", () => {
+    test("should reject empty or invalid input", () => {
+      expect(validateEInvoiceDonationCode("").isValid).toBe(false);
+      expect(validateEInvoiceDonationCode("   ").isValid).toBe(false);
+      // @ts-expect-error Testing invalid input type
+      expect(validateEInvoiceDonationCode(null).isValid).toBe(false);
+      // @ts-expect-error Testing invalid input type
+      expect(validateEInvoiceDonationCode(undefined).isValid).toBe(false);
+    });
+
+    test("should provide meaningful error messages", () => {
+      const result1 = validateEInvoiceDonationCode("12");
+      expect(result1.isValid).toBe(false);
+      expect(result1.message).toBe("捐贈碼必須為3至7位數字");
+
+      const result2 = validateEInvoiceDonationCode("");
+      expect(result2.isValid).toBe(false);
+      expect(result2.message).toBe("捐贈碼必須為非空字串");
+    });
+  });
+});

package/src/validators/einvoice-donation-code.ts

@@ -0,0 +1,42 @@
+import type { ValidationResult } from "../types";
+
+/**
+ * 驗證台灣電子發票捐贈碼
+ * 格式：3-7位數字
+ * 範例：123、12345、1234567
+ *
+ * 捐贈碼用於將電子發票捐贈給已註冊的慈善機構
+ *
+ * @param code - 要驗證的捐贈碼
+ * @returns 驗證結果
+ *
+ * @example
+ * ```typescript
+ * validateEInvoiceDonationCode('123');
+ * validateEInvoiceDonationCode('12345');
+ * ```
+ */
+export function validateEInvoiceDonationCode(code: string): ValidationResult {
+  if (!code || typeof code !== "string") {
+    return {
+      isValid: false,
+      message: "捐贈碼必須為非空字串",
+    };
+  }
+
+  const normalized = code.trim();
+
+  // 檢查格式：3-7位數字
+  const pattern = /^\d{3,7}$/;
+
+  if (!pattern.test(normalized)) {
+    return {
+      isValid: false,
+      message: "捐贈碼必須為3至7位數字",
+    };
+  }
+
+  return {
+    isValid: true,
+  };
+}

package/src/validators/einvoice-mobile-barcode.test.ts

@@ -0,0 +1,67 @@
+import { validateEInvoiceMobileBarcode } from "./einvoice-mobile-barcode";
+
+describe("validateEInvoiceMobileBarcode", () => {
+  describe("Valid Mobile Barcodes", () => {
+    test("should validate correct mobile barcodes", () => {
+      expect(validateEInvoiceMobileBarcode("/ABCD123").isValid).toBe(true);
+      expect(validateEInvoiceMobileBarcode("/1234567").isValid).toBe(true);
+      expect(validateEInvoiceMobileBarcode("/ABC+123").isValid).toBe(true);
+      expect(validateEInvoiceMobileBarcode("/ABC-123").isValid).toBe(true);
+      expect(validateEInvoiceMobileBarcode("/ABC.123").isValid).toBe(true);
+      expect(validateEInvoiceMobileBarcode("/+++++++").isValid).toBe(true);
+      expect(validateEInvoiceMobileBarcode("/-------").isValid).toBe(true);
+      expect(validateEInvoiceMobileBarcode("/.......").isValid).toBe(true);
+    });
+
+    test("should handle case insensitive input", () => {
+      expect(validateEInvoiceMobileBarcode("/abcd123").isValid).toBe(true);
+      expect(validateEInvoiceMobileBarcode("/AbCd123").isValid).toBe(true);
+    });
+
+    test("should handle whitespace", () => {
+      expect(validateEInvoiceMobileBarcode(" /ABCD123 ").isValid).toBe(true);
+    });
+  });
+
+  describe("Invalid Mobile Barcodes", () => {
+    test("should reject barcodes not starting with /", () => {
+      expect(validateEInvoiceMobileBarcode("ABCD123").isValid).toBe(false);
+      expect(validateEInvoiceMobileBarcode("\\ABCD123").isValid).toBe(false);
+    });
+
+    test("should reject incorrect length", () => {
+      expect(validateEInvoiceMobileBarcode("/ABCD12").isValid).toBe(false); // Too short
+      expect(validateEInvoiceMobileBarcode("/ABCD1234").isValid).toBe(false); // Too long
+    });
+
+    test("should reject invalid characters", () => {
+      expect(validateEInvoiceMobileBarcode("/ABCD@23").isValid).toBe(false);
+      expect(validateEInvoiceMobileBarcode("/ABCD#23").isValid).toBe(false);
+      expect(validateEInvoiceMobileBarcode("/ABCD$23").isValid).toBe(false);
+      expect(validateEInvoiceMobileBarcode("/ABCD*23").isValid).toBe(false);
+    });
+  });
+
+  describe("Edge Cases", () => {
+    test("should reject empty or invalid input", () => {
+      expect(validateEInvoiceMobileBarcode("").isValid).toBe(false);
+      expect(validateEInvoiceMobileBarcode("   ").isValid).toBe(false);
+      // @ts-expect-error Testing invalid input type
+      expect(validateEInvoiceMobileBarcode(null).isValid).toBe(false);
+      // @ts-expect-error Testing invalid input type
+      expect(validateEInvoiceMobileBarcode(undefined).isValid).toBe(false);
+    });
+
+    test("should provide meaningful error messages", () => {
+      const result1 = validateEInvoiceMobileBarcode("ABCD123");
+      expect(result1.isValid).toBe(false);
+      expect(result1.message).toBe(
+        "手機條碼必須以 / 開頭，後接7個有效字元（A-Z、0-9、+、-、.）",
+      );
+
+      const result2 = validateEInvoiceMobileBarcode("");
+      expect(result2.isValid).toBe(false);
+      expect(result2.message).toBe("手機條碼必須為非空字串");
+    });
+  });
+});

package/src/validators/einvoice-mobile-barcode.ts

@@ -0,0 +1,45 @@
+import type { ValidationResult } from "../types";
+
+/**
+ * 驗證台灣電子發票手機條碼
+ * 格式：/ + 7個字元（大寫英文字母、數字、+、-、.）
+ * 範例：/ABCD123
+ *
+ * 手機條碼用於將電子發票儲存在手機載具中
+ *
+ * @param barcode - 要驗證的手機條碼
+ * @returns 驗證結果
+ *
+ * @example
+ * ```typescript
+ * validateEInvoiceMobileBarcode('/ABCD123');
+ * validateEInvoiceMobileBarcode('/1234567');
+ * ```
+ */
+export function validateEInvoiceMobileBarcode(
+  barcode: string,
+): ValidationResult {
+  if (!barcode || typeof barcode !== "string") {
+    return {
+      isValid: false,
+      message: "手機條碼必須為非空字串",
+    };
+  }
+
+  const normalized = barcode.trim().toUpperCase();
+
+  // 檢查格式：以 / 開頭，後接7個字元
+  // 有效字元：A-Z、0-9、+、-、.
+  const pattern = /^\/[A-Z0-9+.-]{7}$/;
+
+  if (!pattern.test(normalized)) {
+    return {
+      isValid: false,
+      message: "手機條碼必須以 / 開頭，後接7個有效字元（A-Z、0-9、+、-、.）",
+    };
+  }
+
+  return {
+    isValid: true,
+  };
+}