IBANTools

IBANTools is a TypeScript/JavaScript library focused entirely on one problem: correctly handling International Bank Account Numbers (IBAN), Basic Bank Account Numbers (BBAN), and BIC/SWIFT codes. It validates IBANs against country-specific BBAN structures and checksums, extracts the country code, BBAN, account number, and bank/branch identifiers from a raw IBAN string, and can compose a valid IBAN from its component parts.

The library ships with a built-in registry of country specifications covering the IBAN registry countries plus several non-EU adopters, each encoding the exact BBAN length, character format, and structure needed for real validation rather than a generic regex. It also exposes setCountryBBANValidation so consumers can plug in stricter, country-specific BBAN rules (for example via companion packages like ibantools-germany) without forking the library.

With zero runtime dependencies and builds for CommonJS, ES modules, and AMD/Bower, it slots into Node backends, browser bundles, and legacy RequireJS projects alike, with full TypeScript type definitions bundled in the package.

What You Get

• IBAN validation against per-country BBAN structure and checksum rules, with a detailed validateIBAN result that reports specific error codes instead of just true/false
• IBAN composition (composeIBAN) and extraction (extractIBAN) to build or decompose IBANs into country code, BBAN, account number, and bank/branch identifiers
• BIC/SWIFT validation and extraction, including bank code, country code, location code, and optional branch code parsing
• QR-IBAN detection for Swiss/Liechtenstein payment slips, with an option to reject QR-IBANs during validation
• Extensible country BBAN validation via setCountryBBANValidation, so stricter national rules can be layered in without modifying the library
• Multiple build targets (CommonJS, ES module, AMD) with bundled TypeScript type definitions, so it works in Node, bundled browser apps, and RequireJS projects

Common Use Cases

• Validating IBANs entered into a payment or onboarding form before submitting a SEPA transfer
• Parsing a stored or user-supplied IBAN to extract the bank and branch identifiers for reconciliation or fraud checks
• Generating well-formatted IBANs for display (grouped in blocks of four) from raw account data
• Checking BIC/SWIFT codes supplied alongside an IBAN for structural validity before sending a cross-border payment
• Layering country-specific BBAN checksum rules (e.g. German Prüfziffer methods) on top of the base library via setCountryBBANValidation

Under The Hood

Architecture The entire library is a single well-organized module (src/ibantools.ts, ~1,800 lines) built around a countrySpecs lookup table keyed by ISO country code, where each entry defines BBAN length, structure regex, and optional custom validation/casing functions. Public functions like isValidIBAN, validateIBAN, composeIBAN, and extractIBAN all resolve the country spec first and short-circuit to false/error codes when the code isn’t recognized, keeping the core validation logic (checksum via mod-97, regex-based structure checks) small and centralized rather than spread across per-country classes. The setCountryBBANValidation escape hatch mutates the internal country map directly, making the whole system extensible from outside without touching the core file.

Tech Stack Written in TypeScript and compiled to three separate targets via the tsc CLI: CommonJS (build/) for Node’s require, an ES module build (jsnext/) for bundlers and import, and an AMD build (dist/) for Bower/RequireJS consumers, all wired together through package.json’s exports map. There are zero runtime dependencies — devDependencies only cover the build/test/lint toolchain (TypeScript, ESLint, Prettier, Mocha, Chai, c8 for coverage, TypeDoc for docs).

Code Quality Testing is extensive: test/ibantools_test.js runs over 1,000 lines of Mocha/Chai assertions covering valid and invalid IBANs for dozens of countries, edge cases (null input, wrong checksum, QR-IBAN handling), and BIC validation, plus a small package-entrypoints test verifying the CJS/ESM/type exports resolve correctly. Coverage is tracked via c8 and published to Coveralls, and CI runs both a build/test workflow and a separate ESLint/Prettier workflow on every push, so style and type-checking are enforced automatically. Naming is consistent and the public API is fully documented with TypeDoc-style JSDoc comments including runnable examples.

What Makes It Unique Rather than validating IBANs with a single generic checksum-only regex (which many competing libraries do), IBANTools encodes the exact BBAN structure per country — length, character classes, and where relevant custom bank/branch extraction rules — so it catches malformed account numbers that would otherwise pass a naive mod-97 check. The pluggable setCountryBBANValidation mechanism additionally lets consumers add national-level checksum rules (like Germany’s multiple Prüfziffer methods) as separate packages, keeping the core library lean while still supporting stricter validation where it matters.