npm package: @gateweb/bank-dataset
Description: Gateweb Bank Dataset
Latest version: 1.2.1

# Taiwan Bank Dataset

## Introduction

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

## Installation

### npm

```bash
npm install @gateweb/bank-dataset
```

### yarn

```bash
yarn add @gateweb/bank-dataset
```

### pnpm

```bash
pnpm add @gateweb/bank-dataset
```

## Usage

```typescript
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

```json
{
  "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`）。

```ts
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. 若不存在，回傳空陣列 `[]`。

範例：

```ts
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)`

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

回傳資料結構：

```ts
{
  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` 保留輸入值。

範例：

```ts
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

```ts
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
}
```