npm.io
2.0.0 • Published 4h ago

@dellacagna/iban

Licence
MIT
Version
2.0.0
Deps
0
Size
73 kB
Vulns
0
Weekly
0
Stars
1

npm version CI GitHub license

IBAN Library

A small, dependency-free TypeScript library for validating, formatting, parsing and generating IBAN numbers.

  • Validates country, length, format and the ISO 7064 mod-97 checksum
  • Formats IBANs for screen (GB82 WEST 1234 5698 7654 32) or machines (GB82WEST12345698765432)
  • Extracts the BBAN and fields such as bank code, branch code and account number
  • Generates random, valid IBANs for testing
  • Supports 111 countries: every country in the SWIFT IBAN Registry (ISO 13616), plus countries that use IBAN outside the registry

Installation

npm install @dellacagna/iban

Requires Node.js 18 or later. The package ships both ES modules and CommonJS, with TypeScript types for each.

Upgrading from 1.x? See Migrating to 2.0.

Usage

import { IBAN } from '@dellacagna/iban';

const iban = new IBAN('GB82 WEST 1234 5698 7654 32');

if (iban.isValid()) {
  console.log(iban.toPrintFormat()); // GB82 WEST 1234 5698 7654 32
} else {
  console.log(iban.getError()); // e.g. CHECKSUM_FAILED
}

CommonJS works too:

const { IBAN } = require('@dellacagna/iban');

API

new IBAN(iban: string)

Creates an IBAN object. Input is case-insensitive, and spaces and hyphens are ignored.

isValid(): boolean

Returns true for a valid IBAN or false if invalid.

const iban = new IBAN('GB82 WEST 1234 5698 7654 32');
iban.isValid(); // true
getError(): errorCodes | undefined

Returns why the IBAN is invalid, or undefined if it is valid. The possible values are exported as the errorCodes enum:

errorCodes Value Meaning
invalidCountry INVALID_COUNTRY The country code is not supported
invalidLength INVALID_LENGTH Wrong length for the country
invalidFormat INVALID_FORMAT Characters don't match the country's BBAN format
checksumFailed CHECKSUM_FAILED The check digits are wrong (e.g. a typo in the number)
import { IBAN, errorCodes } from '@dellacagna/iban';

const iban = new IBAN('GB82 WEST 1234');
iban.getError(); // 'INVALID_LENGTH'

if (iban.getError() === errorCodes.invalidLength) {
  // ...
}
getOriginal(): string

Returns the original input, unchanged.

new IBAN('GB82 weST 123456987654   32').getOriginal(); // 'GB82 weST 123456987654   32'
toElectronicFormat(): string

Returns the IBAN in upper case with all spaces and hyphens removed.

new IBAN('GB82 weST 123456987654   32').toElectronicFormat(); // 'GB82WEST12345698765432'
toPrintFormat(): string

Returns the IBAN in upper case, in groups of four characters.

new IBAN('GB82 weST 123456987654   32').toPrintFormat(); // 'GB82 WEST 1234 5698 7654 32'
getBBAN(): string

Returns the BBAN (Basic Bank Account Number): the IBAN without the country code and check digits.

new IBAN('GB82 WeST 1234 5698 7654 32').getBBAN(); // 'WEST12345698765432'
getFields(): Fields | undefined

Returns the fields contained in the IBAN. Fields that don't apply to the country are left out. Returns undefined for unsupported countries and for countries with no published field layout.

interface Fields {
  countryCode: string;
  country: string;
  checkDigits: string;
  accountNumber?: string;
  currencyCode?: string;
  ownerAccountNumber?: string;
  accountNumberPrefix?: string;
  bankCode?: string;
  bicBankCode?: string;
  branchCode?: string;
  accountType?: string;
  nationalCheckDigit?: string;
}
new IBAN('BA39 1290 0794 0102 8494').getFields();
// {
//   countryCode: 'BA',
//   country: 'Bosnia and Herzegovina',
//   checkDigits: '39',
//   accountNumber: '94010284',
//   bankCode: '129',
//   branchCode: '007',
//   nationalCheckDigit: '94',
// }

getFields() does not check that the IBAN is valid; call isValid() first.

IBAN.random(countryCode?: string): string

Generates a random IBAN with valid check digits, in print format. Pass a country code (case-insensitive) to choose the country; otherwise one is picked at random. The result is structurally valid but almost certainly not a real account, so it is only meant for tests and fake data.

IBAN.random(); // e.g. 'GB82 WEST 1234 5698 7654 32'
IBAN.random('IT'); // e.g. 'IT60 X054 2811 1010 0000 0123 456'
IBAN.random('US'); // throws RangeError: Unsupported IBAN country code: US

Throws a RangeError if the country is not supported.

IBAN.supportedCountries(): string[]

Returns the country codes of all supported countries, sorted alphabetically.

IBAN.supportedCountries(); // ['AD', 'AE', 'AL', ...]
IBAN.isSupportedCountry(countryCode: string): boolean

Returns true if the country (case-insensitive) is supported.

IBAN.isSupportedCountry('gb'); // true
IBAN.isSupportedCountry('US'); // false
Static helpers

The formatting methods are also available without creating an object:

IBAN.electronicFormat('gb82 west 1234 5698 7654 32'); // 'GB82WEST12345698765432'
IBAN.printFormat('GB82WEST12345698765432'); // 'GB82 WEST 1234 5698 7654 32'
IBAN.bban('GB82 WEST 1234 5698 7654 32'); // 'WEST12345698765432'
IBAN.extractFields('BA39 1290 0794 0102 8494'); // same as getFields()

Supported countries

The library covers every country in the SWIFT IBAN Registry, including recent additions such as the Falkland Islands, Mongolia, Oman, Somalia and Yemen.

It also supports 23 countries that use IBAN but are not in the official registry. Their formats come from national banks and are not guaranteed by SWIFT, and getFields() returns undefined for them:

Algeria (DZ), Angola (AO), Benin (BJ), Burkina Faso (BF), Cabo Verde (CV), Cameroon (CM), Central African Republic (CF), Chad (TD), Comoros (KM), Congo (CG), Côte d'Ivoire (CI), Equatorial Guinea (GQ), Gabon (GA), Guinea-Bissau (GW), Honduras (HN), Iran (IR), Madagascar (MG), Mali (ML), Morocco (MA), Mozambique (MZ), Niger (NE), Senegal (SN), Togo (TG).

Migrating to 2.0

  • Node.js 18+ is required, and the build targets ES2018 instead of ES5. If you need to support very old browsers, transpile the package in your bundler.
  • IBAN.random('XX') throws a RangeError for unsupported countries instead of quietly returning an IBAN for a random country. Use IBAN.isSupportedCountry() to check first.
  • getError() returns the errorCodes enum instead of string. The runtime values are unchanged ('INVALID_LENGTH' etc.), but TypeScript may now flag comparisons with plain strings. Compare with errorCodes.invalidLength instead.
  • The package has an exports map. Only the package root (@dellacagna/iban) can be imported; deep imports such as @dellacagna/iban/dist/lib/constants no longer work. Everything you need is exported from the root.

Development

npm install
npm test               # Jest
npm run lint           # ESLint
npm run typecheck      # tsc --noEmit
npm run build          # ESM + CommonJS + types in dist/ (tsup)
npm run check:exports  # verify the package resolves for ESM, CommonJS and TypeScript

Resources

Keywords