Taiwan Bank Dataset

Introduction

這是一個提供完整臺灣銀行機構代碼與分行代碼資料的 npm 套件。包含所有主要銀行的機構代碼、分行代碼以及對應的中文名稱，方便在各種專案中使用。

Installation

npm

npm install @gateweb/bank-dataset

yarn

yarn add @gateweb/bank-dataset

pnpm

pnpm add @gateweb/bank-dataset

Usage

import { BankCodeMap, type BankData, type BranchData } from '@gateweb/bank-dataset';

// 型別安全的使用方式
function findBankByCode(code: string): BankData | undefined {
  return BankCodeMap.find((bank) => bank.code === code);
}

function findBranchByCode(bankCode: string, branchCode: string): BranchData | undefined {
  const bank = findBankByCode(bankCode);
  return bank?.branch.find((branch) => branch.code === branchCode);
}

Data Example

{
  "code": "004",
  "name": "臺灣銀行",
  "isClosed": false,
  "branch": [
    {
      "code": "0037",
      "name": "營業部",
      "isClosed": false
    },
    {
      "code": "0071",
      "name": "館前分行",
      "isClosed": false
    }
  ]
}

API Reference

| 名稱 | 類型 | 說明 | | ------------------------------------ | ----------------------------------------------------- | ---------------------------------------------------- | | BankCodeMap | BankData[] | 全部銀行與分行的資料陣列。 | | getBranchList(bankCode) | (bankCode: string) => BranchData[] | 取得指定銀行代碼的全部分行列表，若不存在回傳空陣列。 | | getBankInfo(bankCode, branchCode?) | (bankCode: string, branchCode?: string) => BankInfo | 取得銀行與分行的名稱資訊（包含格式化全名）。 |

BankCodeMap

完整的銀行與分行資料陣列。可直接用於建立索引、快取、或前端下拉選單。請勿在執行期修改此陣列內容，若需過濾或轉換請以純函式操作（如 map / filter）。

import { BankCodeMap } from '@gateweb/bank-dataset';

const allBankCodes = BankCodeMap.map((b) => b.code);
const taiwanBank = BankCodeMap.find((b) => b.code === '004');

getBranchList(bankCode: string)

取得指定銀行代碼的分行陣列。

行為說明：

1. 若 bankCode 存在於資料集中，回傳其 branch 陣列。
2. 若不存在，回傳空陣列 []。

範例：

import { getBranchList } from '@gateweb/bank-dataset';

const branches = getBranchList('004');
// [ { code: '0037', name: '營業部', isClosed: false }, { code: '0059', name: '公庫部', isClosed: false }, ... ]

const notFound = getBranchList('999');
// []

getBankInfo(bankCode: string, branchCode?: string)

取得銀行與（可選）分行的資訊，並組合友善展示的完整名稱。此函式不會拋出錯誤；若代碼無效則以空字串填充相關欄位。

回傳資料結構：

{
  bankCode: string;
  bankName: string; // 若無效為 ''
  bankFullName: string; // 格式："{bankCode} {bankName}"，若無效為 ''
  isBankClosed: boolean | null; // 銀行是否已關閉，無效銀行為 null
  branchCode: string; // 若未傳入或無效仍保留輸入值
  branchName: string; // 若無效為 ''
  branchFullName: string; // 格式："{branchCode} {branchName}"，若無效為 ''
  isBranchClosed: boolean | null; // 分行是否已關閉，無效分行為 null
}

行為規則：

1. 只傳 bankCode：回傳銀行資訊，分行欄位為空字串。
2. 傳入有效 bankCode + 有效 branchCode：回傳完整銀行與分行資訊。
3. 傳入有效 bankCode + 無效 branchCode：分行欄位保持空字串，branchCode 保留原輸入值方便除錯。
4. 傳入無效 bankCode：所有名稱欄位皆為空字串，bankCode/branchCode 保留輸入值。

範例：

import { getBankInfo } from '@gateweb/bank-dataset';

// 只查銀行
getBankInfo('004');
// {
//   bankCode: '004',
//   bankFullName: '004 臺灣銀行',
//   bankName: '臺灣銀行',
//   isBankClosed: false,
//   branchCode: '',
//   branchFullName: '',
//   branchName: '',
//   isBranchClosed: null
// }

// 查銀行 + 分行
getBankInfo('004', '0037');
// {
//   bankCode: '004',
//   bankFullName: '004 臺灣銀行',
//   bankName: '臺灣銀行',
//   isBankClosed: false,
//   branchCode: '0037',
//   branchFullName: '0037 營業部',
//   branchName: '營業部',
//   isBranchClosed: false
// }

// 無效分行
getBankInfo('004', '9999');
// {
//   bankCode: '004',
//   bankFullName: '004 臺灣銀行',
//   bankName: '臺灣銀行',
//   isBankClosed: false,
//   branchCode: '9999',
//   branchFullName: '',
//   branchName: '',
//   isBranchClosed: null
// }

// 無效銀行
getBankInfo('999');
// {
//   bankCode: '999',
//   bankFullName: '',
//   bankName: '',
//   isBankClosed: null,
//   branchCode: '',
//   branchFullName: '',
//   branchName: '',
//   isBranchClosed: null
// }

Types

interface BranchData {
  code: string; // 分行代碼 Branch code
  name: string; // 分行名稱 Branch name
  isClosed: boolean; // 分行是否已關閉 Is the branch closed
}

interface BankData {
  code: string; // 銀行代碼 Bank code
  name: string; // 銀行名稱 Bank name
  branch: BranchData[]; // 分行列表 Branch list
  isClosed: boolean; // 銀行是否已關閉 Is the bank closed
}