bank-idn

Database kode bank Indonesia, validator nomor rekening, formatter, dan generator.

TypeScript-first, zero dependencies, 100% test coverage, dual ESM+CJS, tree-shakeable.

npm install bank-idn

Tidak perlu database, API call, atau file eksternal. Cukup install dan langsung pakai.

Fitur

• Database 105 bank — BUMN, swasta, syariah, digital, BPD, asing
• Validasi rekening — cek kode bank, format, dan panjang nomor rekening
• Format rekening — standard (dash), masked (bintang), spaced, compact
• Generate rekening — buat nomor rekening valid untuk testing, seeding, atau demo
• Pencarian bank — cari bank berdasarkan kode, nama, atau singkatan
• SWIFT/BIC code — kode SWIFT untuk transfer internasional
• Discriminated union — return type aman di-narrow pakai result.valid
• Error bahasa Indonesia — semua pesan error dalam bahasa Indonesia
• Tree-shakeable — import hanya fungsi yang dibutuhkan
• TypeScript-first — strict types, auto-complete di IDE
• Dual ESM + CJS — support semua environment
• Zero dependencies — tidak ada dependency runtime
• 100% coverage — statements, branches, functions, lines

Struktur Kode Bank

Kode bank Indonesia menggunakan 3-digit kode BI (Bank Indonesia).

014 → Bank Central Asia (BCA)
002 → Bank Rakyat Indonesia (BRI)
008 → Bank Mandiri
009 → Bank Negara Indonesia (BNI)

| Kategori | Jumlah | Contoh | |----------|--------|--------| | BUMN | 4 | BRI, Mandiri, BNI, BTN | | Swasta | 39 | BCA, Danamon, Permata, CIMB Niaga | | Syariah | 9 | BSI, BCA Syariah, Muamalat | | Digital | 14 | Jago, Allo, Seabank, Blu BCA | | BPD | 26 | Bank DKI, Bank Jatim, Bank Jabar Banten | | Asing | 13 | Citibank, HSBC, Standard Chartered |

Quick Start

import { getBank, validateAccount, formatAccount, generateAccount } from 'bank-idn';

// Lookup bank — cari informasi bank
const bank = getBank("014");
console.log(bank);
// { code: "014", name: "Bank Central Asia", shortName: "BCA",
//   swift: "CENAIDJA", type: "swasta", accountLengths: [10] }

// Validasi — cek apakah nomor rekening valid
const valid = validateAccount("014", "1234567890");
console.log(valid); // { valid: true }

// Format — tampilkan nomor rekening dalam format tertentu
const masked = formatAccount("014", "1234567890", "masked");
console.log(masked); // "******7890"

// Generate — buat nomor rekening untuk testing
const account = generateAccount({ bankCode: "014" });
console.log(account); // { bankCode: "014", accountNumber: "8234561290" }

API Reference

getBank(code: string): Bank | undefined

Lookup informasi bank berdasarkan kode BI.

import { getBank } from 'bank-idn';
// atau: import { getBank } from 'bank-idn/banks';

getBank("014");
// { code: "014", name: "Bank Central Asia", shortName: "BCA",
//   swift: "CENAIDJA", type: "swasta", accountLengths: [10] }

getBank("999"); // undefined

getBanks(): ReadonlyArray<readonly [string, Bank]>

Daftar semua bank sebagai array of tuples [code, bank].

import { getBanks } from 'bank-idn';

const banks = getBanks();
// [["002", { code: "002", name: "Bank Rakyat Indonesia", ... }], ...]

getBanksByType(type: BankType): Bank[]

Filter bank berdasarkan kategori.

import { getBanksByType } from 'bank-idn';

getBanksByType("bumn");    // 4 bank BUMN
getBanksByType("swasta");  // 39 bank swasta
getBanksByType("syariah"); // 9 bank syariah
getBanksByType("digital"); // 14 bank digital
getBanksByType("bpd");     // 26 bank BPD
getBanksByType("asing");   // 13 bank asing

searchBank(query: string): Bank[]

Cari bank berdasarkan kode, nama, atau singkatan. Case-insensitive, partial match.

import { searchBank } from 'bank-idn';

searchBank("BCA");
// [{ code: "014", name: "Bank Central Asia", shortName: "BCA", ... },
//  { code: "501", name: "Bank Digital BCA", shortName: "Blu BCA", ... },
//  { code: "536", name: "Bank BCA Syariah", shortName: "BCA Syariah", ... }]

searchBank("mandiri");
// [{ code: "008", name: "Bank Mandiri", ... }]

validateAccount(bankCode: unknown, accountNumber: unknown): ValidationResult

Validasi nomor rekening secara bertahap (fail-fast).

import { validateAccount } from 'bank-idn';
// atau: import { validateAccount } from 'bank-idn/validate';

validateAccount("014", "1234567890");       // { valid: true }
validateAccount("014", "123-456-7890");     // { valid: true } — separator diterima
validateAccount("014", "123");              // { valid: false, error: "..." }
validateAccount("999", "1234567890");       // { valid: false, error: "..." }

formatAccount(bankCode: string, accountNumber: string, format?: AccountFormat): string

Format nomor rekening ke format tertentu. Throws jika input tidak valid.

import { formatAccount } from 'bank-idn';
// atau: import { formatAccount } from 'bank-idn/format';

formatAccount("014", "1234567890", "standard"); // "123-456-789-0"
formatAccount("014", "1234567890", "masked");   // "******7890"
formatAccount("014", "1234567890", "spaced");   // "1234 5678 90"
formatAccount("014", "1234567890", "compact");  // "1234567890"
formatAccount("014", "1234567890");             // "123-456-789-0" (default: standard)

| Format | Output | Keterangan | |--------|--------|------------| | standard | 123-456-789-0 | Grouped per 3 digit dengan dash | | masked | ******7890 | Hanya 4 digit terakhir terlihat | | spaced | 1234 5678 90 | Grouped per 4 digit dengan spasi | | compact | 1234567890 | Digit saja, tanpa separator |

generateAccount(options?: GenerateOptions): GenerateResult

Generate nomor rekening valid untuk testing.

import { generateAccount } from 'bank-idn';
// atau: import { generateAccount } from 'bank-idn/generate';

// Full random
generateAccount();
// { bankCode: "014", accountNumber: "8234561290" }

// Bank spesifik
generateAccount({ bankCode: "014" });
// { bankCode: "014", accountNumber: "5678901234" }

// Kategori bank
generateAccount({ type: "bumn" });
// { bankCode: "002", accountNumber: "123456789012345" }

// Kombinasi (bankCode harus sesuai type)
generateAccount({ bankCode: "014", type: "swasta" });

BANK_MAP: ReadonlyMap<string, Bank>

Map lengkap kode bank ke informasi bank. Untuk advanced use case.

import { BANK_MAP } from 'bank-idn';

BANK_MAP.size;           // 105
BANK_MAP.get("014");     // { code: "014", name: "Bank Central Asia", ... }
BANK_MAP.has("014");     // true

Validasi yang Dilakukan

| # | Pengecekan | Error | |---|-----------|-------| | 1 | Kode bank harus string | Kode bank harus berupa string | | 2 | Kode bank tidak boleh kosong | Kode bank tidak boleh kosong | | 3 | Kode bank harus terdaftar | Kode bank "XXX" tidak terdaftar | | 4 | Nomor rekening harus string | Nomor rekening harus berupa string | | 5 | Nomor rekening tidak boleh kosong | Nomor rekening tidak boleh kosong | | 6 | Hanya digit (setelah sanitize) | Nomor rekening hanya boleh berisi angka | | 7 | Panjang sesuai bank | Nomor rekening BCA harus 10 digit |

Input yang Diterima

validateAccount dan formatAccount menerima separator dalam nomor rekening:

| Format | Contoh | |--------|--------| | Digit saja | 1234567890 | | Dengan dash | 123-456-7890 | | Dengan spasi | 1234 5678 90 | | Dengan titik | 123.456.7890 | | Dengan underscore | 123_456_7890 |

Tree-shaking / Sub-path Imports

import { getBank, searchBank } from 'bank-idn/banks';
import { validateAccount } from 'bank-idn/validate';
import { formatAccount } from 'bank-idn/format';
import { generateAccount } from 'bank-idn/generate';
import type { Bank, ValidationResult, AccountFormat } from 'bank-idn/types';

Types

import type {
  Bank,
  BankType,
  AccountFormat,
  ValidationValid,
  ValidationInvalid,
  ValidationResult,
  GenerateOptions,
  GenerateResult,
} from 'bank-idn/types';

Contributing

git clone https://github.com/sumitroajiprabowo/bank-idn.git
cd bank-idn
npm install
npm run lint          # Lint check (Biome)
npm run format:check  # Format check
npm run typecheck     # TypeScript check
npm run test:coverage # Test dengan coverage (harus 100%)
npm run build         # Build ESM + CJS

Changelog

Lihat CHANGELOG.md untuk riwayat perubahan.

Lisensi

MIT (c) Sumitro Aji Prabowo